First encounter

First Encounter is part of a free web series, ChemPlugin Modeling with Python, by Aqueous Solutions LLC.

What you need:

Download this unit to use in your courses:

Click on a file to open, or right-click and select “Save link as…” to download.

Introduction to Python

Python is a widely used programming language with a number of favorable characteristics:

  • Scripting runs directly without compiling
  • Easy to learn
  • Rapid prototyping and development
  • Strong support for data structures and objects
  • High productivity
  • Oh, the libraries!

Python is a very readable language. Consider the simple example below showing how indentation is used to delimit code blocks in Python in place of brackets

    edibles = ["ham", "eggs", "spam", "nuts"]
    for food in edibles:
        if food == "spam":
            print("No more spam please!")
        print("Great " + food)
    print("I'm done eating!")

The simple script will print out

        Great ham
        Great eggs
        No more spam please!
        I'm done eating!

It is best practice to use spaces, not tabs. Four spaces per indent level is standard.

ChemPlugin is a software object. Consider the following syntax for using an object in Python:

    from SomeObject import *        # "SomeObject" is installed & pointed to by PYTHONPATH
    my_instance = SomeObject()      # SomeObject's constructor. "my_instance" is a reference.
    my_instance.do_this(my_way)     # Calls to member functions "do_this" and "do_that".
    del my_instance                 # Remove reference. Garbage collection is automatic.

There are a number of ways to work with Python. First, you can work interactively from the Command Prompt

work interactively

You may wish to work instead with a simple development environment consisting of a text editor and the Command Prompt

simple development environment

Finally, an Integrated Development Environment, such as Microsoft Visual Studio

integrated development environment

can very useful for professional programming. For the purposes of this course, however, the simple development environment of Notepad++ and the Command Prompt will suffice.

Task 1: Working from the Command Prompt

Let's work with Python interactively. Start the Command Prompt and type “python”

The Command prompt should look like this:

To create a ChemPlugin instance, import the ChemPlugin() object and call its constructor by typing:

    from ChemPlugin import *
    cp = ChemPlugin("stdout")

You should see the following:

To configure the instance, use the “Config()” member function along with your desired configuration commands. As an example, type:

    cp.Config("Na+ = 10 mmol/kg")
    cp.Config("balance on Cl-")

A non-zero return indicates failure, while a zero means success. The “show” configuration command describes how the ChemPlugin instance is set up. Typing


should give you:

The “Initialize()” member function finds the initial state of the instance you've configured. Once the state is known, you can use the “Report1()” member function to query the instance for a specific calculation result. Type:

    x = cp.Report1("concentration NaCl")
    print("m NaCl =", x)

The Command Prompt should show

the species loaded into the ChemPlugin instance's calculation, a “0” indicating a successful initialization, and the concentration of the NaCl ion pair in molal units (mol kg−1 solvent).

Task 2: Working with Python scripts

Working interactively from the Command Prompt is useful as you get started using ChemPlugin with Python, but once you get comfortable it's often easier to prepare Python scripts. A simple development environment consisting of a text editor and the command prompt serves this purpose well.

Open Notepad++ and prepare a script by typing the commands below, then save the file to your Desktop as “”.

    from ChemPlugin import *
    cp = ChemPlugin("stdout")

    cp.Config("Na+ = 10 mmol/kg")
    cp.Config("balance on Cl-")


    x = cp.Report1("concentration NaCl")
    print("m NaCl =", x)

These are the same commands we typed into the Command Prompt interactively in the previous exercise. Notepad++ should look like this:

Next, start the Command Prompt. Set your working directory to the Desktop (or wherever you saved your Python script) and read in the script. To do so, type

    cd Desktop

The Command Prompt should look like this:

To run the script by double-clicking on the file, return to Notepad++ and add an “input” statement.

After saving the script, you can double-click to run it. The window won't close until you hit return.

For more information, please refer to the Overview chapter of the ChemPlugin™ User's Guide.


Craig M. Bethke and Brian Farrell. © Copyright 2016–2023 Aqueous Solutions LLC. This lesson may be reproduced and modified freely to support any licensed use of The Geochemist's Workbench® software, provided that any derived materials acknowledge original authorship.


Bethke, C.M., 2022, Geochemical and Biogeochemical Reaction Modeling, 3rd ed. Cambridge University Press, New York, 520 pp.

Bethke, C.M., 2023, The Geochemist's Workbench®, Release 17: ChemPlugin™ User's Guide. Aqueous Solutions LLC, Champaign, IL, 303 pp.

Comfortable with the first encounter?

Move on to the next topic, Time Marching Loops, or return to the ChemPlugin Modeling with Python home.