Equi2Py: Convert Equilib calculation files to Python scripts

Equi2Py is a package that converts FactSage Equilib calculation files (*.equi) to Python scripts or Jupyter notebooks. Release artifacts are distributed as a wheel named, for example, equi2py-1.0.17-py3-none-any.whl, and as a source archive named equi2py-1.0.17.tar.gz.

Installation

Equi2Py can be installed through the GUI Tools that come with the FactSage software package, or from a wheel using:

pip install equi2py-1.0.17-py3-none-any.whl

The source archive can be installed in the same way:

pip install equi2py-1.0.17.tar.gz

The package requires chemapp, and is compatible to any version of Python that chemapp is compatible with.

Using Equi2Py

You can run Equi2Py as a command-line tool or call its conversion function from your own code.

Command Line Tool

You can use Equi2Py as a command line tool by running the following command:

python -m equi2py --equi "Example.equi" --db "Example_database.cst" --format py --out "Example.py" --include_examples

The --equi option identifies the Equilib calculation file and --db its .cst or .dat database. The --format option selects a Python script (py) or notebook (ipynb), while --out specifies the output path. Additional flags control optional sections of the generated file.

You can explore these options by running:

python -m equi2py --help

If you omit an option configured for interactive input, the tool prompts you for it. Because these are named options, their order is not important.

Calling Examples

To create a Jupyter notebook that includes some examples, use the following command:

python -m equi2py --equi "Example.equi" --db "Example_database.cst" --format ipynb --out "Example.ipynb" --include_examples

To create a Jupyter notebook that includes database information code and saves into a file called reactor.ipynb:

python -m equi2py --equi "Example.equi" --db "Example_database.cst" --out "reactor.ipynb" --format ipynb --include_info

To create a Python script that includes database information code and saves it as test.py:

python -m equi2py --equi "Example.equi" --db "Example_database.cst" --out "test.py" --format py

Using Equi2Py in Your Code

Import convert from the package root:

from equi2py import convert

convert(
    equi="Example.equi",
    db="Example_database.cst",
    format="py",
    include_examples=True,
)

In this example, omitting out writes Example.py next to Example.equi. The function accepts the following arguments:

  • equi (str or path-like, required): Equilib .equi input file.

  • db (str or path-like, required): .cst or .dat database file.

  • format (“py” or “ipynb”, optional): Output format. Defaults to "py".

  • out (str, path-like, or None, optional): Output path. If omitted, the input filename is used with the suffix selected by format.

  • include_status (bool, optional): Include explicit phase and constituent status setup. Defaults to False.

  • include_examples (bool, optional): Include example calculations. Defaults to False.

  • include_info (bool, optional): Include database information code. Defaults to False.

  • debug (bool, optional): Print parsed conversion data and option values. Defaults to False.

The function returns None and copies the database file into the output directory.