.. _equi2py:

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. The package is distributed as a
``.tar.gz`` archive with a name such as ``equi2py-1.0.9.tar.gz``.


Installation
************

Equi2Py can be installed through the GUI Tools that come with the FactSage
Software package, or simply using::

    pip install equi2py-1.0.9.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 include the functions to generate
Python scripts in 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 --include_examples

which requires the file path of the Equilib calculation file and the database
file. You can also specify the output file name using the ``--out`` flag, and
some options to add or remove certain sections of the output file.

You can explore these options by running::

    python -m equi2py --help

If you omit the required arguments, the tool will prompt you to enter them. The
order of arguments 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 --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 Jupyter Notebook that includes database information code and saves
into a file called ``test.py``::

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


Using Equi2Py in Your Code
==========================

You can use the functions in your code by importing the package and calling the
following function::
    
        from equi2py import convert
    
        convert("Example.equi", "Example_database.cst", format="py", include_examples=True)

The function provides the same options as the command line tool, as the
following arguments:

- *equi* (**Path**, required): The Equilib file that should be converted.
- *db* (**Path**, required): Database file to be used. Can be either .cst or .dat file.
- *format* ([**py** | **ipynb**], required): output file type, either 'py' or 'ipynb'.
- *out* (**Path**): Filename of output file.
- *include_status* (**bool**): Flag to enable the inclusion of explicit status setup.
- *include_examples* (**bool**): Flag to enable the inclusion of examples.
- *include_info* (**bool**): Flag to enable the inclusion of datafile information.