First encounter

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

---

Introduction to Python

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

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!")
            break
        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".
    my_instance.do_that(your_way)
    
    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

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

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

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

    cp.Config("show")
                

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:

    cp.Initialize()
    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⁻¹ 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 “NaCl.py”.

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

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

    cp.Initialize()

    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
    NaCl.py
                

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.

---

Authors

Craig M. Bethke and Brian Farrell. © Copyright 2016–2024 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.

References

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

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

---