API Documentation

DESPASITO has been primarily designed as a command line tool but can be used as an imported package. See Basic Use or despasito.examples directory for more details.

Command Line

DESPASITO: Determining Equilibrium State and Parametrization Application for SAFT, Intended for Thermodynamic Output. This is an open-source application for thermodynamic calculations and parameter fitting for equations of state (EOS) like the Statistical Associating Fluid Theory (SAFT) EOS.

usage: python -m despasito [-h] [-i INPUT] [-v] [--log [LOGFILE]] [-n NCORES]
                           [-p PATH] [-c] [--numba] [--python] [--cython]

Named Arguments

-i, --input

Input file in JSON format with calculation instructions and path(s) to equation of state parameters. See documentation for explicit explanation. Compile docs or visit https://despasito.readthedocs.io

-v, --verbose

Verbose level: repeat up to three times for Warning, Info, or Debug levels.

Default: 0

--log

Name of output a log file.

Default: 'despasito.log'

-n, --ncores

Set the number of cores used. A value of -1 will request all possible resources.

Default: 1

-p, --path

Set the location of the data/library files (e.g. SAFTcross, etc.) where despasito will look.

Default: '.'

-c, --console

Enable logs to print to standard output.

Default: False

--numba

Turn on Numba’s JIT compilation for accelerated computation

Default: True

--python

Run calculation in python without compiled modules.

Default: False

--cython

Turn on Cython for accelerated computation

Default: False

Imported Package

Once installed, DESPASITO can be easily imported with import despasito. Each module will then need to replicate our main command line function and call each module in succession.

  1. Generate Eos object used in thermodynamic calculations with initiate_eos.

  2. Start thermodynamic calculation with thermo where the calculation type and Eos object will specify the thermodynamic calculation.

Alternatively, the Eos object can be used for independent study.

The intermediate logging provided in the Input File Schema can also be accessed for imported functions through the initiate_logger.

Input File Schema

General Keywords

  • bead_configuration: (list[list[list]]) - This list contains the system components. Each component is defined as a list of the bead types of which it is composed. Each bead type is represented by a list where the first entry is the bead name (used in the EOSgroup file) and second entry is the integer number of beads in the component. See tutorial, Setting-up a Thermodynamic Calculation.

  • EOSgroup: (str) - The filename of a file in the JSON format containing a dictionary of single group parameters used in the desired equation of state (EOS).

  • EOScross: (str) - The filename of file in the JSON format containing a dictionary of group-group cross interaction parameters used in the desired equation of state (EOS).

  • calculation_type: (str) - Any calculation_type that is supported by the thermodynamic module.

  • output_file: (str) Optional - default: despasito_out.txt. Output file name for results of a thermodynamic calculation.

  • eos: (str) Optional - default: saft.gamma_mie. Supported EOS class to be used in thermodynamic computations.

  • eos_*: Optional - Any keyword that needs to be passed to an equation of state object should be preceded by “eos_” to be includes in the eos dictionary (e.g. num_rings for saft.gamma_mie should be included as eos_num_rings).

  • *: Required or optional keywords from the chosen calculation_type. See appropriate doc string for more details.

Parameter Fitting Keywords

  • optimization_parameters: The presence of this keyword signifies that a parameter fitting calculation is requested.

    • fit_bead: (str) - Name of bead whose parameters are being fit, must be in bead list of bead_configuration.

    • fit_parameter_names: (list[str]) - This list contains the name of the parameter being fit (e.g. epsilon). See EOS documentation for supported parameter names. Cross interaction parameter names should be composed of parameter name and the other bead type, separated by an underscore (e.g. epsilon_CO2).

    • parameters_guess: (list[float]), Optional - Initial guess in parameter. If one is not provided, a guess is made based on the type of parameter from Eos object.

    • *_bounds: (list[float]) Optional, default is provided by Eos object. By putting a parameter name before the “bounds” suffix, the lower and upper limit of the parameter is defined for the fitting process. Defining the bounds is recommended for rapid convergence.

  • *: Experimental data dictionaries may be defined using any keyword, although this key is later used in distinguishing the respective objective function value. Any number of experimental data dictionaries may be included. A keyword is specified as an experimental data structure with the presence of the keyword “data_class_type” and an entry.

    • data_class_type: (str) Defines a supported data class for fitting.

    • calculation_type: (str) Optional - Any calculation_type that is supported by the thermodynamic module.

    • file: (str) Optional - File of experimental data, See fitting data class for file headers.

    • bead_configuration: (list[float]), Optional - Initial guess in parameter. If one is not provided, a guess is made based on the type of parameter from Eos object. This allows the specified bead to be fit using multiple systems.

    • weights: (dict) Optional - A dictionary where each key is the header used in the exp. data file. The value associated with a header can be a list as long as the number of data points to multiply by the objective value associated with each point, or a float to multiply the objective value of this data set.

    • *: Optional - Instead of a file of experimental data, the relevant arrays may be included here. All other optional entries for the calculation_type may be included.

  • global_opts: (dict), Optional - Specify details of global optimization method.

    • method: (str), default: ‘differential_evolution’, Global optimization method used to fit parameters. See global_minimization().

    • *: any keyword used by the defined global optimization method. Note that unless the keyword, workers is provided, the thermodynamic calculation will we split among the cores. Check the global optimization method to ensure it uses the workers keyword.

  • minimizer_opts: (dict), Optional - Dictionary used to define minimization type used by the global optimization method.

    • method: (str) - Method available to scipy.optimize.minimize.

    • options: (dict) - This dictionary contains the kwargs available to the chosen method.

See fit for more information.