pycte

PYCTE (PYthon generiC inTerfacE) couples speciation solvers (PhreeqC, ORCHESTRA, xGEMS, native speciation and kinetics) with transport solvers (COMSOL, PFLOTRAN, and a native 1D transport code) by operator splitting.

PYCTE is distributed under the Apache 2.0 license that can be found in the LICENSE file. By using, distributing, or contributing to this project, you agree to the terms and conditions of this license.

Installation

Python 3.11 or newer.

pip install pycte

This installs every Python dependency (numpy, pandas, scipy, charset-normalizer, phreeqpy, h5py, mph). From a copy of the sources, run pip install . in the folder containing pyproject.toml (pip install -e . for development).

Check the installation:

python -c "import pycte; print(pycte.examples())"

Solvers

pycte only needs the solvers you use:

Quick start

Run first the test case matching your solvers:

import pycte

pycte.load("CementClayInterface")    # PhreeqC, multi-compound transport
pycte.chemModule("orchestra")        # switch solver: the example's database and initial conditions follow
pycte.MCT(False)                     # multi-species transport (option of this example)
pycte.maxTime(100)                   # any setting can be overridden, before or after a solver switch
pycte.output({"coupling": [50, 100]})   # output steps must lie within the run (here 100 steps of 1 year)

if __name__ == "__main__":
    pycte.run()

The outputs are written in the current folder. When you shorten a bundled example with pycte.maxTime(...), also give output steps within the new run with pycte.output(...): the example's own output steps may lie beyond it. Keep pycte.run() under if __name__ == "__main__": on Windows as soon as several processes are used (PIDnbr > 1).

Bundled test cases

pycte.chemModule(...) and pycte.trsptModule(...) switch to the files of the example for that solver. The settings you give after pycte.load(...) are kept whatever the order of the calls.

Your own case

Each setting read by pycte has its own function, e.g. pycte.maxTime(72000), pycte.timeStep(720), pycte.chemPath("my.dat"), pycte.initialConditions("ic.txt"); a misspelled setting raises an AttributeError. The older style, a script defining the settings as variables (chemModule = 'phreeqc', maxTime = 1e5, ...) and ending with pycte.run(), still works.

Outputs

• warning.log: run description, every warning (solvers, Python, workers) and the computation times;
• coupling/Coupling_<step>.txt: the coupled variables at the steps asked with pycte.output({'coupling': [...]});
• orchestra_output.log: ORCHESTRA solver messages.

Post-processing:

df = pycte.postProcess(["Ca", "Cl"], "myRunFolder")                    # breakthrough curves (last cell)
dp = pycte.postProcess(columnProfile=(["Ca", "Cl"], "myRunFolder"))    # profiles at the last step
times = pycte.getTimes("myRunFolder")                                   # computation times, warnings count

PFLOTRAN runs in the folder of its input file and updates it: with a bundled example, copy the example's .in file and the files it names (e.g. its DATABASE) next to your script, and give it with pycte.trsptPath(...).

Building a release (maintainers)

python -m pip install build twine
python -m build              # dist/pycte-<version>.tar.gz and .whl, built with setuptools >= 77
python -m twine upload dist/pycte-<version>*

Remove older files from dist/ first, or upload only the new version. The version is set in pyproject.toml; data files of a new example must be declared in [tool.setuptools] (packages and package-data).

Do not hesitate to contact me ! (anatole.lafond [at] cea.fr)