.. _sec.cli:

Command line interface
======================

You can run simulation from the command lines with ``DyssolC.exe``, which can be found in the installation directory. Usage: 

.. code-block:: shell

    DyssolC.exe --key[=value] [--key[=value] [...]]

|

+-----------------+-----------+--------------------------------------------+
| Key             | Short key | Example                                    |
+=================+===========+============================================+
| \-\-script      | -s        | DyssolC.exe \-\-script="script.txt"        |
+-----------------+-----------+--------------------------------------------+
| \-\-version     | -v        | DyssolC.exe \-\-version                    |
+-----------------+-----------+--------------------------------------------+
| \-\-models      | -m        | DyssolC.exe -m                             |
+-----------------+-----------+--------------------------------------------+
| \-\-models_path | -mp       | DyssolC.exe -m -mp="models1" -mp="models2" |
+-----------------+-----------+--------------------------------------------+
| \-\-help        | -h        | DyssolC.exe \-\-help                       |
+-----------------+-----------+--------------------------------------------+

``--script`` defines a script file, and it is a required key needed to start simulation. Script is a text file describing all necessary parameters for your simulation file. Details about the script keys are described below.

You can find exemplary script files in the installation directory under ``Example Scripts``.

Only 3 script keys from the list are mandatory: ``SOURCE_FILE`` or ``RESULT_FILE``, ``MODELS_PATH``, and ``MATERIALS_DATABASE``. The rest are optional and will override parameters set in initial file, specified as ``SOURCE_FILE``. If ``SOURCE_FILE`` is not defined, the script should describe the entire flowsheet with all parameters, and ``RESULT_FILE`` is required. If ``RESULT_FILE`` parameter is not specified, results of the simulation will be written to a ``SOURCE_FILE``.

script keys ``MODELS_PATH``, ``DISTRIBUTION_GRID``, ``UNIT``, ``STREAM``, ``UNIT_PARAMETER``, ``UNIT_HOLDUP_*``, ``EXPORT_STREAM_*``, ``EXPORT_HOLDUP_*``, ``EXPORT_UNIT_*`` can be mentioned several times in the script file, the rest should be places only once.

Main
----

+--------------------+--------------------------------+--------------------------------------------------------------+
| Script key         | Value                          | Description                                                  |
+====================+================================+==============================================================+
| JOB                |                                | Delimiter for a sequentially executed job within one script  |
+--------------------+--------------------------------+--------------------------------------------------------------+
| SOURCE_FILE        | <path>                         | Full path to a \*.dflw file with initial flowsheet           |
+--------------------+--------------------------------+--------------------------------------------------------------+
| RESULT_FILE        | <path>                         | Full path to a file where simulation results will be written |
+--------------------+--------------------------------+--------------------------------------------------------------+
| MODELS_PATH        | <path>                         | Path to the directory with libraries of units and solvers    |
+--------------------+--------------------------------+--------------------------------------------------------------+
| MATERIALS_DATABASE | <path>                         | Full path to the file with materials database                |
+--------------------+--------------------------------+--------------------------------------------------------------+

|
	
Simulation
----------

Simulation options
^^^^^^^^^^^^^^^^^^

+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| Script key                   | Value                                   | Description                                                                                                                |
+==============================+=========================================+============================================================================================================================+
| SIMULATION_TIME              | <value>                                 | End simulation time [s]                                                                                                    |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| RELATIVE_TOLERANCE           | <value>                                 | Global relative tolerance                                                                                                  |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| ABSOLUTE_TOLERANCE           | <value>                                 | Global absolute tolerance                                                                                                  |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| MINIMAL_FRACTION             | <value>                                 | Minimum significant fraction in MD matrices                                                                                |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| SAVE_TIME_STEP_HINT          | <value>                                 | Save time step hint [s] for streams                                                                                        |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| SAVE_FLAG_FOR_HOLDUPS        | YES/NO                                  | Apply save time step hint for holdups and internal streams                                                                 |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| THERMO_TEMPERATURE_MIN       | <value>                                 | Min of temperature range [K] where mixtures can be calculated                                                              |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| THERMO_TEMPERATURE_MAX       | <value>                                 | Max of temperature range [K] where mixtures can be calculated                                                              |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| THERMO_TEMPERATURE_INTERVALS | <value>                                 | Number of intervals to calculate temperature of mixtures                                                                   |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| INIT_TIME_WINDOW             | <value>                                 | Initial time window [s]                                                                                                    |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| MIN_TIME_WINDOW              | <value>                                 | Min size of time window [s]                                                                                                |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| MAX_TIME_WINDOW              | <value>                                 | Max size of time window [s]                                                                                                |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| MAX_ITERATIONS_NUMBER        | <value>                                 | Max allowed number of iterations                                                                                           |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| WINDOW_CHANGE_RATE           | <value>                                 | Rate of change of the time window                                                                                          |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| TERATIONS_UPPER_LIMIT        | <value>                                 | Upper limit of iterations for adjusting time window size                                                                   |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| ITERATIONS_LOWER_LIMIT       | <value>                                 | Lower limit of iterations for adjusting time window size                                                                   |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| ITERATIONS_UPPER_LIMIT_1ST   | <value>                                 | Upper limit of iterations for adjusting time window size of the 1st window                                                 |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| RELAXATION_PARAMETER         | <value>                                 | Relaxation parameter for DIRECT_SUBSTITUTION (0;1]                                                                         |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| ACCELERATION_LIMIT           | <value>                                 | Axxeleration parameter limit for WEGSTEIN (-5;1)                                                                           |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| CONVERGENCE_METHOD           | DIRECT_SUBSTITUTION/WEGSTEIN/STEFFENSEN | Convergence method                                                                                                         |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+
| EXTRAPOLATION_METHOD         | NEAREST_NEIGHBOR/LINEAR/CUBIC_SPLINE    | Extrapolation method                                                                                                       |
+------------------------------+-----------------------------------------+----------------------------------------------------------------------------------------------------------------------------+

|

Phases
^^^^^^

+------------+---------------------------------------------------------+----------------+
| Script key | Value                                                   | Description    |
+============+=========================================================+================+
| PHASES     | <name> SOLID/LIQUID/GAS [<name> SOLID/LIQUID/GAS [...]] | Defined phases |
+------------+---------------------------------------------------------+----------------+

|

Compounds
^^^^^^^^^

+------------+-----------------------------------+-------------------------------------------+
| Script key | Value                             | Description                               |
+============+===================================+===========================================+
| COMPOUNDS  | <key>/<name> [<key>/<name> [...]] | Defined compounds from materials database |
+------------+-----------------------------------+-------------------------------------------+

|

Grids
^^^^^

+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+
| Script key                 | Value                                                                                                                                                                                                | Description                                                                                                                            |
+============================+======================================================================================================================================================================================================+========================================================================================================================================+
| KEEP_EXISTING_GRIDS_VALUES | YES/NO                                                                                                                                                                                               | Whether to keep grids defined in SOURCE_FILE. If set to NO, all grids are removed before applying any DISTRIBUTION_GRID. Default = YES |
+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+
| DISTRIBUTION_GRID          | GLOBAL/<unit_name>/<unit_index> SIZE/PARTICLE_POROSITY/FORM_FACTOR/COLOR/USER_DEFINED_** SYMBOLIC <classes_number> <values>                                                                          | Definition of a symbolic grid                                                                                                          |
+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+
| DISTRIBUTION_GRID          | GLOBAL/<unit_name>/<unit_index> SIZE NUMERIC MANUAL/EQUIDISTANT/GEOMETRIC_INC/GEOMETRIC_DEC/LOGARITHMIC_INC/LOGARITHMIC_DEC DIAMETER/VOLUME <classes_number> <values>                                | Definition of a numeric size grid                                                                                                      |
+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+
| DISTRIBUTION_GRID          | GLOBAL/<unit_name>/<unit_index> PARTICLE_POROSITY/FORM_FACTOR/COLOR/USER_DEFINED_** NUMERIC MANUAL/EQUIDISTANT/GEOMETRIC_INC/GEOMETRIC_DEC/LOGARITHMIC_INC/LOGARITHMIC_DEC <classes_number> <values> | Definition of a numeric non-size grid                                                                                                  |
+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------+

|

Flowsheet structure
^^^^^^^^^^^^^^^^^^^

+---------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| Script key          | Value                                                                                                                      | Description                                                                                                               |
+=====================+============================================================================================================================+===========================================================================================================================+
| KEEP_EXISTING_UNITS | YES/NO                                                                                                                     | Whether to keep units defined in SOURCE_FILE. If set to NO, all units are removed before applying any UNIT. Default = YES |
+---------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| UNIT                | <name> <model_id>/<model_name>/<lib_path>                                                                                  | Definition of a unit                                                                                                      |
+---------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
| STREAM              | <name> <o_unit_name>/<o_unit_index> <o_port_name>/<o_port_index> <i_unit_name>/<i_unit_index> <i_port_name>/<i_port_index> | Definition of a stream                                                                                                    |
+---------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+

|

Unit parameters
^^^^^^^^^^^^^^^

+----------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| Script key     | Value                                                                                                                                       | Description                                                         |
+================+=============================================================================================================================================+=====================================================================+
| UNIT_PARAMETER | <unit_name>/<unit_index> <param_name/param_index> <value> [<value> [...]]                                                                   | Definition of a constant/string/compound/flag/solver unit parameter |
+----------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| UNIT_PARAMETER | <unit_name>/<unit_index> <param_name/param_index> <time> <value> [<time> <value> [...]]                                                     | Definition of a time-dependent unit parameter                       |
+----------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| UNIT_PARAMETER | <unit_name>/<unit_index> <param_name/param_index> <subs_number> <base_subs> <name> <nu> <order> <phase> [<name> <nu> <order> <phase> [...]] | Definition of a reaction unit parameter                             |
+----------------+---------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+

|

Holdups
^^^^^^^

+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| Script key                   | Value                                                                                                                                                                                                                                   | Description                                                                                                                              |
+==============================+=========================================================================================================================================================================================================================================+==========================================================================================================================================+
| KEEP_EXISTING_HOLDUPS_VALUES | YES/NO                                                                                                                                                                                                                                  | Whether to keep holdups defined in SOURCE_FILE. If set to NO, all holdups values are removed before applying any HOLDUP_*. Default = YES |
+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| HOLDUP_OVERALL               | <unit_name>/<unit_index> <holdup_name>/<holdup_index> <values>                                                                                                                                                                          | Overall (mass/mass flow, temperature, pressure) stream properties for a single time point 0 [s]                                          |
+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| HOLDUP_OVERALL               | <unit_name>/<unit_index> <holdup_name>/<holdup_index> <time> <values> [<time> <values> [...]]                                                                                                                                           | Overall (mass/mass flow, temperature, pressure) stream properties for several time points [s]                                            |
+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| HOLDUP_PHASES                | <unit_name>/<unit_index> <holdup_name>/<holdup_index> <values>                                                                                                                                                                          | Mass fractions of all defined phases for a single time point 0 [s]                                                                       |
+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| HOLDUP_PHASES                | <unit_name>/<unit_index> <holdup_name>/<holdup_index> <time> <values> [<time> <values> [...]]                                                                                                                                           | Mass fractions of all defined phases for several time points [s]                                                                         |
+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| HOLDUP_COMPOUNDS             | <unit_name>/<unit_index> <holdup_name>/<holdup_index> SOLID/LIQUID/GAS <values>                                                                                                                                                         | Compounds mass fractions of all defined compounds in a selected phase for a single time point 0 [s]                                      |
+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| HOLDUP_COMPOUNDS             | <unit_name>/<unit_index> <holdup_name>/<holdup_index> SOLID/LIQUID/GAS <time> <values> [<time> <values> [...]]                                                                                                                          | Compounds mass fractions of all defined compounds in a selected phase for several time points [s]                                        |
+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| HOLDUP_DISTRIBUTION          | <unit_name>/<unit_index> <holdup_name>/<holdup_index> SIZE MIXTURE/<compound_key>/<compound_name> MASS_FRACTION/NUMBER/Q*_DENSITY/Q*_CUMULATIVE DIAMETER/VOLUME MANUAL/NORMAL/LOG_NORMAL/RRSB/GGS [time] <values> [time <values> [...]] | Particle size distribution                                                                                                               |
+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+
| HOLDUP_DISTRIBUTION          | <unit_name>/<unit_index> <holdup_name>/<holdup_index> PARTICLE_POROSITY/FORM_FACTOR/COLOR/USER_DEFINED_** MIXTURE/<compound_key>/<compound_name> MANUAL/NORMAL/LOG_NORMAL/RRSB/GGS [time] <values> [time <values> [...]]                | Other distributions aside from particle size distribution                                                                                |
+------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------+

|

Export
^^^^^^

+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| Script key                        | Value                                                                        | Description                                                                         |
+===================================+==============================================================================+=====================================================================================+
| EXPORT_FILE                       | <path>                                                                       | Full path to a text file where to export all data                                   |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_PRECISION                  | <value>                                                                      | Precision for floating point output. Default = 6                                    |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_FIXED_POINT                | YES/NO                                                                       | Formatting for floating-point output. Default = NO                                  |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_SIGNIFICANCE_LIMIT         | <value>                                                                      | Values whose absolute value is less than this will be interpreted as 0. Default = 0 |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_ONLY                       | YES/NO                                                                       | Perform only export (no simulation) within this JOB. Default = NO                   |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_STREAM_MASS                | <stream_name>/<stream_index> [<time_points>]                                 | Export mass flows of a stream                                                       |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_STREAM_TEMPERATURE         | <stream_name>/<stream_index> [<time_points>]                                 | Export temperatures of a stream                                                     |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_STREAM_PRESSURE            | <stream_name>/<stream_index> [<time_points>]                                 | Export pressures of a stream                                                        |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_STREAM_OVERALLS            | <stream_name>/<stream_index> [<time_points>]                                 | Export all overall properties (mass flow, temperature, pressure) of a stream        |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_STREAM_PHASES_FRACTIONS    | <stream_name>/<stream_index> [<time_points>]                                 | Export phases mass fractions of a stream                                            |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_STREAM_COMPOUNDS_FRACTIONS | <stream_name>/<stream_index> [<time_points>]                                 | Export compounds mass fractions of a stream                                         |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_STREAM_PSD                 | <stream_name>/<stream_index> [<time_points>]                                 | Export particle size distributions of a stream                                      |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_STREAM_DISTRIBUTIONS       | <stream_name>/<stream_index> [<time_points>]                                 | Export distributed parameters of a stream                                           |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_HOLDUP_MASS                | <unit_name>/<unit_index> <holdup_name>/<holdup_index> [<time_points>]        | Export mass a unit's holdup                                                         |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_HOLDUP_TEMPERATURE         | <unit_name>/<unit_index> <holdup_name>/<holdup_index> [<time_points>]        | Export temperatures of a unit's holdup                                              |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_HOLDUP_PRESSURE            | <unit_name>/<unit_index> <holdup_name>/<holdup_index> [<time_points>]        | Export pressures of a unit's holdup                                                 |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_HOLDUP_OVERALLS            | <unit_name>/<unit_index> <holdup_name>/<holdup_index> [<time_points>]        | Export all overall properties (mass, temperature, pressure) of a unit's holdup      |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_HOLDUP_PHASES_FRACTIONS    | <unit_name>/<unit_index> <holdup_name>/<holdup_index> [<time_points>]        | Export phases mass fractions of a unit's holdup                                     |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_HOLDUP_COMPOUNDS_FRACTIONS | <unit_name>/<unit_index> <holdup_name>/<holdup_index> [<time_points>]        | Export compounds mass fractions of a unit's holdup                                  |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_HOLDUP_PSD                 | <unit_name>/<unit_index> <holdup_name>/<holdup_index> [<time_points>]        | Export particle size distributions of a unit's holdup                               |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_HOLDUP_DISTRIBUTIONS       | <unit_name>/<unit_index> <holdup_name>/<holdup_index> [<time_points>]        | Export distributed parameters of a unit's holdup                                    |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_UNIT_STATE_VARIABLE        | <unit_name>/<unit_index> <var_name>/<var_index>                              | Export state variable of a unit                                                     |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_UNIT_PLOT                  | <unit_name>/<unit_index> <plot_name>/<plot_index> <curve_name>/<curve_index> | Export plot values of a unit                                                        |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
| EXPORT_FLOWSHEET_GRAPH            | <path>                                                                       | Export flowsheet graph as a \*.png file                                             |
+-----------------------------------+------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+

|