OLI Model Configuration

Navigation: Models ➔ TCE Models ➔ OLI ➔ OLI Model Configuration

OLI Overview	OLI Database Utility	OLI Model Configuration	OLI Direct Calc	OLI Side Calc	OLI Reactor 2	OLI Evaporator	OLI Flash Tank	OLI Reverse Osmosis	OLI Solvent Extraction	OLI Feeder	OLI Pond (Dynamic)

Latest SysCAD Version: 25 October 2024 - SysCAD 9.3 Build 139.36522

Related Links: OLI SysCAD Project Workflow, OLI Example Project

Legacy Models: OLI Chemistry Model. This legacy model is used for backward compatibility purposes. We highly recommend users convert any existing project to use this new OLI unit model: OLI Model Configuration.

---

Available from Build 139.31866. The above set of OLI unit models uses OLI version 11 or later.

General Description

OLI Systems is a leading Electrolyte Simulation Software used to predicate equilibrium conditions and properties (such as pH) for aqueous chemistry. It is developed and maintained by OLI Systems (olisystems.com).

This model allows the user to select the OLI database file to be used in SysCAD and some configuration of its use. The two main functions are to select a OLI Database File (*.dbs) (refer to Referenced File) and then for the selected Database file, 'map' OLI species/ions to SysCAD species/ions used in the project. This allows the other OLI models in SysCAD to convert the SysCAD species flow data to OLI species data (and vice-versa) and use the OLI functionality to calculate aqueous equilibrium data.

The model does not do any calculations and has no process links to any other models in SysCAD flowsheets. Its sole purpose is for management and configuration of a selected OLI Database, other unit models performing OLI calculations will reference this model. Therefore, this model is essential if the user wishes to use the OLI functionality in SysCAD.

NB: The user MUST have a licensed version of "OLI Engine Runtime" on their computer. Please see OLI Overview for more information.

Referenced File

The user may need to have an OLI Database file (*.dbs) before initialising the SysCAD OLI Model Configuration. Please see Referenced File for instructions on how to create this file.

Diagram

The diagram shows the default drawing of a OLI Model Configuration unit model.

Inputs and Outputs

There are no connections to this unit.

Model Theory

OLI requires a defined input stream which defines almost all species in ionic form (no phase). At the given conditions (temperature, pressure), OLI returns an output stream which includes aqueous ions in solution and any precipitates (solids) as species.

The OLI Model Configuration defines the mapping of SysCAD species to OLI ions/species to define the required input stream, and the convert the OLI output stream back to SysCAD species.

A diagram is provided below to explain the mapping process. Red lines represent the mapping criteria.

Notes:

• Some automatic mapping functions are available to match species based on molecular weights and elements.
• Users can also manually adjust the mappings by selecting matching ions/species from dropdown lists.
• Where more than one ionic breakdown reactions is available for a SysCAD species (defined in IonList.txt), the user can choose which one or combination to use.
• SysCAD species can be selected to bypass the OLI calculations by excluding them from the defined OLI input stream.
• OLI solid species can also be excluded from being formed as part of the OLI output stream.
• Ion Definitions are provided in IonList.txt. These are used to calculate SysCAD species breakdowns.

Workflow

The suggested workflow for configuring the model is:

2. On the OLIModelCfg tab page, select required dll or for older dll formats the .dbs file from dropdown list. If only 1 database is available, then this will automatically be selected.
3. On the OLIModelCfg tab page, press the Load button to load the dll or for older dll formats the .dbs file.
4. Map the OLI ions and species to SysCAD ions and species on the OLIConfig tab page. The simplest way to do this is to press the Try Map Species button next to Map on the OLIConfig tab page.
5. If required, make adjustments to the SatIndex on the OLIConfig tab page.
7. If required, set the species reverse mapping Algorithm on the OLIConfig tab page.
8. If required, make any adjustments to the selection of Ion Breakdown reactions on the IonicBreakdown tab page.
9. Once these steps are performed and the mappings are checked, the project can be run.

NOTES:

1. The OLI Direct Calc Model does not require species mapping between OLI and SysCAD. If the user wants to perform OLI Direct Calculations only, then only Steps 1 and 2 are required from the above workflow.
2. Any other OLI unit models such as the OLI Side Calc Model or OLI Reactor referencing this OLI Model Configuration unit model will use the mappings defined.

Data Sections

The tabs and variable names are described in detail in the following tables.

1. OLIModelCfg tab - This first tab requires the user select the OLI database file and has various related options and parameters.
2. OLIConfig tab - This tab requires the user to map the OLI ions/species to the equivalent species/ions in SysCAD, so that OLI stream compositions can be converted to a SysCAD stream and vice-versa.
3. ScdSpMap tab - This tab reports the SysCAD to OLI species mapping as a result of choices made on the OLIConfig tab page, so the SysCAD stream composition can be converted to a OLIstream.
4. ScdIonMap tab - This tab reports the SysCAD to OLI ion mapping as a result of choices made on the OLIConfig tab page, so the SysCAD stream composition can be converted to a OLIstream.
5. IonicBreakdown tab - This tab lists the Ion Breakdown reactions for SysCAD species and allows the user to select which ones to use.
6. UsedBy tab - This tab displays the OLI model units referencing to this OLI Model configuration unit.
7. Engines tab - This tab contains information about the OLI Engines.
8. Info tab - contains general settings for the unit and allows the user to include documentation about the unit and create Hyperlinks to external documents.

OLI Model Configuration tab page

Unit Type: OLIModelCfg - The first tab page in the access window will have this name.

Tag (Long/Short)	Input / Calc	Description/Calculated Variables / Options
Tag	Display	This name tag may be modified with the change tag option.
Condition	Display	OK if no errors/warnings, otherwise lists errors/warnings.
ConditionCount	Display	The current number of errors/warnings. If condition is OK, returns 0.
GeneralDescription / GenDesc	Display	This is an automatically generated description for the unit. If the user has entered text in the 'EqpDesc' field on the Info tab (see below), this will be displayed here. If this field is blank, then SysCAD will display the UnitType or SubClass.
This program contains OLI Engine Copyright OLI Systems, USA
Interface...
Acknowledgement	Display	This program contains OLI Engine Copyright OLI Systems, USA
Website	Web Link	https://www.olisystems.com
Version	Display	This displays the version of OLI installed on the user's computer
Model...
Select OLI database file
DatabaseFile/DBFile	Input	This is the name of the database file that was created by OLI, e.g. OLI001.dbs. It is chosen from a dropdown list of available databases, which are defined in the cfg file for the project.
DatabaseFilePath/DBFilePath	Display	The folder where the database file shown above is saved.
CheckForSteam	Tickbox	If ticked, SysCAD will check if steam (H2O(g)) is included in the list of OLI species.
Load		Click on this button to load the required database file.
DefnStatus	List	If the OLI database file has been loaded and no errors have been detected then will show OK, otherwise will show error message.
SpDBCount	Display	The number of species loaded from the OLI database file.
Sol.Count	Display	The number of solid species loaded from the OLI database file.
Liq.Count	Display	The number of liquid species loaded from the OLI database file.
Vap.Count	Display	The number of gaseous species loaded from the OLI database file.
ElemCount	Display	The number of elements loaded from the OLI database file.
RedoxEnabled	Display	Indicates whether the model has oxidation-reduction reactions enabled.
Liq2Enabled	Display	Available from Build 139.34985. This indicates whether the model has a second liquid phase enabled, which is a requirement for OLI Solvent Extraction. For instructions on how to enable the second liquid phase, please refer to Liquid 2 Functionality in SysCAD.
ElemList	Display	The list of the elements used in the OLI database file.
Mapping Tolerances
Discard.Tol.SigDigits	Input	This provides an easy way to change the Discard.Tol.Rel value. For example, 4 here will set 1.00e-4 to Discard.Tol.Rel. If user changes the Discard.Tol.Rel value, this value will also be updated.
Discard.Tol.Rel	Input	The relative tolerance for ignoring species produced from the OLI calculations. If the mass fraction of a species is > DiscardTol and it is not mapped to a SysCAD species/ion then an error is generated.
ElemBal.Tol.SigDigits	Input	This provides an easy way to change the ElemBal.Tol.Rel value. For example, 4 here will set 1.00e-4 to ElemBal.Tol.Rel. If user changes the ElemBal.Tol.Rel value, this value will also be updated.
ElemBal.Tol.Rel	Input	The relative tolerance for Element Balance (Input - Output). If the relative error is > ElemBal.Tol.Rel then an error is generated. The value of ElemBal.Tol.Rel specified here is used in all OLI unit models which reference this OLI Model Configuration unit model.
ElemBal.Tol.Abs	Input	The absolute tolerance for Element Balance (Input - Output). If the absolute error is > ElemBal.Tol.Abs then an error is generated. The value of ElemBal.Tol.Abs specified here is used in all OLI unit models which reference this OLI Model Configuration unit model.
Convergence Tolerances
EnthConv.Tol.SigDigits	Input	This provides an easy way to change the EnthConv.Tol.Rel value. For example, 4 here will set 1.00e-4 to EnthConv.Tol.Rel. If user changes the EnthConv.Tol.Rel value, this value will also be updated.
EnthConv.Tol.Rel	Input	Enthalpy convergence tolerance. This is used for iterative enthalpy convergence calculations in SysCAD.
Species Without Enthalpy Data Tolerance (Mass Fraction)
SpHfMissing.Tol	Input	For species which do not have complete enthalpy information, i.e. either H25 or Cp is missing, the mass fraction of the species above which a warning is issued.
TotHfMissing.Tol	Input	The total mass fraction of all species with missing Cp or H25 data above which a warning is issued.

OLI Config tab page

This tab is used to map the OLI species/ions to the SysCAD species/ions.

Tag (Long/Short)	Input / Calc	Description/Calculated Variables / Options
OLIConfig...
SpeciesName		The Species:Long or Short button is used to change the display of the Species names between the Short form, the Chemical compound, or the longer species names.
Map OLI species/ions to SysCAD species/ions
Map / MapByElements		This will try to map the OLI species/ions to the SysCAD species/ions based on their Elemental definition.
CheckMap / CheckMapByElements		This will check the mapping of the OLI species/ions to the SysCAD species/ions based on their Elemental definition. Any unexpected results in the current mappings will be displayed as warnings in the Messages Window.
MissingIons		This adds the missing ions to the IonList.txt file. The project must be reloaded before the added ions can be mapped. This button will be disabled if all required ions already exist in the IonList.txt file. In this case, pressing will map all ions.
MaximumMWDiff / MaxMWDiff	Input	This is the maximum allowed difference between molecular weights of mapped species without generating a warning.
MaximumChargeDiff / MaxChargeDiff	Input	This is the maximum allowed charge difference between mapped species without generating a warning.
FwdIonMap.PhasesAllowed Available from Build 139.33457.	All	When converting the SysCAD species to the OLI input file, all species can be mapped to ions. See IonicBreakdown tab page.
	Liquids Only	When converting the SysCAD species to the OLI input file, only liquid species can be mapped to ions. See IonicBreakdown tab page.
	Aqueous Only	When converting the SysCAD species to the OLI input file, only aqueous species can be mapped to ions. See IonicBreakdown tab page.
	Sol, Vap & Aq	When converting the SysCAD species to the OLI input file, only solid, vapour and aqueous species can be mapped to ions. See IonicBreakdown tab page.
RevIonMap.PhasesAllowed Available from Build 139.33457.	Aqueous Only	Ions in the OLI output file can only be reverse-mapped to SysCAD aqueous species.
ReverseMappingAlgorithm / MappingAlgorithm	Simple Extent	Species are built in order of reaction extent, with no regard for if they are acids, bases, or salts.
	Salts First	Salts are built preferentially. Remaining form acids and bases. Each group is built in order of reaction extent. Recommended in most cases.
RevIonMap.BreakdownFirst	Input	If checked, species are assembled from primary ions, i.e. the smallest possible ions. If not, they are assembled from ions predicted by the equilibrium solution. Recommendation is NOT checked.
SpDBCount	Display	The number of species/ionss defined in the OLI database.
SpUsedCount	Display	The number of species/ions in the OLI database that are used in the project.
SpMappedCount	Display	The number of species/ions in the OLI database that have been mapped to equivalent SysCAD species/ions.
SpCFECount	Display	The number of species/ions in the OLI database that can be used with CFE (constrained free energy).
DetailedGridView	Tickbox	Global selection. If enabled, more fields will be shown in grid views (tables) including the tables on this page.
SuppressVisible		User can suppress the formation of all species currently visible by pressing this button. The Sup option for all species currently visible will be ticked when you press this button.
UnsuppressVisible		User can disable the suppress option of all species currently visible by pressing this button. The Sup option for all species currently visible will be unticked when you press this button.
CopyToClipboard		Adds a table of data to the clipboard making it available to be pasted into other applications. Columns include SysCAD species, OLI species, SysCAD molecular weight, OLI molecular weight, mapping type and saturation index.
Filter View
Filter		This button will enable or disable the species filter options.
ShowUnmapped (Only visible if Filter is enabled)	Tickbox	When enabled, all species will be displayed. When disabled, only species that are mapped to a SysCAD species will be shown.
Phases (Only visible if Filter is enabled)	All	No filtering of species based on phase.
	Solids	Only show solid phase species, hide other species.
	Liquids	Only show liquid phase species, hide other species.
	Vapours	Only show vapour (gaseous) phase species, hide other species.
	Solids & Liquids	Only show solid and liquid phase species, hide other species.
	Solids & Vapours	Only show solid and vapour (gaseous) phase species, hide other species.
	Liquids & Vapours	Only show liquid and vapour (gaseous) phase species, hide other species.
	IPhase	Only show "IPhase" individual phase species, hide other species. The individual phases shown will depend on the OLI database chosen.
Filters	Display	Always set to 'Content'.
Content (Only visible if Filter is enabled)	All	No filtering of species based on element or name.
	Contains Any Element	This will display all species that contain any of the elements entered in their elemental definition.
	Contains All Elements	This will display only species that contain ALL of the elements entered in their elemental definition.
	Starts with ...	This will display species that start with the text entered based on the short or long species tag depending on the current SpeciesTag selection.
	Contains any ...	This will display species that contain the text entered in the currently displayed short or long species tag.
	Contains All ...	This will display species that contain ALL the separate text entered in the currently displayed short or long species tag.
Select	Input	Only visible if Filter is enabled and Content is NOT set to All. The user specified Elements or text to filter the species list. Refer to Species Filter for more information and examples.
(The following tables (one per phase) display the OLI species/ions from the selected database and the mapped SysCAD species/ions. The user can choose, or change, the mapped SysCAD species/ions using the dropdown list.) (Each table has the following columns (one row per OLI species/ions):)
Sup	Tickbox	User can suppress the formation of species by ticking this option. Note that suppressing species may have a profound effect on the final chemistry, so a good understanding of actual process chemistry is very important when building a predictive model.
MoleWt	Display	The Molecular Weight of the OLI species/ions.
ElemDefn	Display	The Elemental Definition of the OLI species/ions.
Charge	Display	Only shown if DetailedGridView has been enabled. The electrical charge of the OLI species/ions.
Index	Display	Only shown if DetailedGridView has been enabled. The index of the OLI species/ions.
MappedIon	List	The user may select the most appropriate SysCAD ion from a dropdown list to map to the OLI ion. The relationship between ions and species in SysCAD is defined on the IonicBreakdown tab page. It is expected that OLI ions would be mapped to SysCAD ions. This column is not shown for solid and gas species.
MappedSpecies	List	The user may select the most appropriate SysCAD species from a dropdown list to map to the OLI species.
MapSpByEl	Button	Only shown if DetailedGridView has been enabled. If pressed, SysCAD will try to find the most appropriate SysCAD species to map to this OLI species by matching elemental compositions.

ScdSpMap tab page

This tab is used to display the mapping of SysCAD species to OLI species. This is often a 1 to 1 mapping.

Tag (Long/Short)	Input / Calc	Description/Calculated Variables / Options
SysCAD to OLI mapping
ScdSpMap...
(The following table displays all the SysCAD species in the project with its mapped OLI species (if there is one).) (The table has the following columns (one row per SysCAD species):)
Mapping	Display	The name of the first mapped OLI species (if there is one).
Select	List	If there are multiple OLI species with same elemental definition, allows user to choose which one to map to the corresponding SysCAD species.
MapType	Direct	There is an exact match of species between "SysCAD species database/cfg file" and the loaded OLI database, and the species is allowed by the license option and mapped directly on the OLIConfig page.
	Ions	The species is not mapped on the OLIConfig page, but can be broken down to valid ions (ionlist.txt).
	Unmapped	Species exist in the loaded OLI database, but not in the "SysCAD species database/cfg file". User may consider adding the species to the SysCAD database if it is required.
	Unlicensed	There is an exact match of species between "SysCAD species database/cfg file" and the loaded OLI database, but the species is not allowed by the license option.
MapCount	Display	The number of OLI species that are mapped to the relevant SysCAD species.
MW_Diff	Display	The difference in Molecular Weights between the SysCAD species and the first mapped OLI species (shown in the name column).

ScdIonMap tab page

This tab is used to display the mapping of SysCAD ions to OLI ions. This is usually a 1 to 1 mapping.

Tag (Long/Short)	Input / Calc	Description/Calculated Variables / Options
SysCAD Ions to OLI mapping
ScdIonMap...
(The following table displays all the SysCAD ions in the project with its mapped OLI ion (if there is one).) (The table has the following columns (one row per SysCAD ion):)
Name	Display	The name of the mapped OLI ion (if there is one).
MW_Diff	Display	The difference in Molecular Weights between the SysCAD ion and the the mapped OLI ion (shown in the name column).
CalcFormableSp	Tickbox	If selected, SysCAD will show the SysCAD molecular species that can be formed from the selected ions.
(The following fields are only shown if the CalcFormableSp option has been enabled for at least one ion.
Selected Ions:
x formable species from y selected ions
Formable...
SpX	Display	The name of a SysCAD molecular species that can be formed from one or more of the selected ions.

IonicBreakdown tab page

This tab displays the Ion Breakdown reaction for the SysCAD species. SysCAD Ions are defined in the IonList.txt file, normally located in \"Project Group"\Cfgfiles folder. The reactions displayed are calculated by SysCAD and represent the ionic breakdown pathway of the species which produces the largest number of product moles. In other words, species are broken down into the smallest possible ions.

Tag (Long/Short)	Input / Calc	Description/Calculated Variables / Options
IBR...
Ion Breakdown Reactions for Species
The following table displays all the SysCAD species in the project with their Ion Breakdown reaction/s. The table has one row per breakdown reaction
CopyToClipboard		Pressing the Ion Breakdown button will give two options: Selecting Species will copy the ion breakdown for all species. (top table) Selecting Species And Ions will copy the ion breakdown for species and ions, including further breakdown of larger ions.
IonListFile		Pressing this button will open the IonList.txt file being used by the project. Note that any edits of the IonList.txt file will only be reflected after model reload and remapping of the species.
Ion Breakdown reactions	Display	The relevant SysCAD species that is assumed to breakdown as per the specified reaction.
Ion Breakdown Reactions for Larger Ions
(The following table displays all the complex ions in the project (if any) with their Ion Breakdown reaction/s to simpler ions.)
Ion Breakdown reactions	Display	The relevant SysCAD species that is assumed to breakdown as per the specified reaction.

NOTE: The species listed on this page are determined by the phase selection in the "OLIConfig tab page - FwdIonMap.PhasesAllowed" option.

UsedBy tab page

Tag (Long/Short)	Input / Calc	Description/Calculated Variables / Options
List of all connected Unit Models using this ModelCfg
UsedBy...
Count	Display	The number of units models that are using this Model Configuration.
(The following table displays the OLI unit models referencing to this OLIModelCfg model.)
MX	Display	The unit model (X) referencing the OLIModelCfg model.
On	Display	The On/Off state of the OLI unit model referencing this OLIModelCfg model.
UnitType	Display	Displays the UnitType type of the OLI unit model referencing this OLIModelCfg model.
UnitTag	Display	The tag of the OLI unit model referencing this OLIModelCfg model.
AllConnected.Feed	Button	Generate a composite report of all feed streams of units connected to this OLIModelCfg model.
AllConnected.Prod	Button	Generate a composite report of all product streams of units connected to this OLIModelCfg model.

Engines tab page

The number of engines used can be set in the SysCAD configuration (.cfg) file.

Tag (Long/Short)	Input / Calc	Description/Calculated Variables / Options
This program contains OLI Engine Copyright OLI Systems, USA
Global Engines for OLI Interface
Interface...
Engines.Status	OK	The model has been initialised correctly and the database file has been found and loaded correctly.
	Init Required	The model needs to be initialised.
	Init Failed	The model initialisation has been attempted but failed.
	Not installed	The OLI software is not installed.
	Wrong Version	The wrong version of the OLI software is installed.
	DLL not licensed	The OLI software is not licensed.
Reload		If the user clicks on the 'Reload' button, then it will Reload the OLI engine/s.
InitTime	Display	The time taken to initialise the model on the last attempt.
Engines.WaitTime	Display	The time when all engines are busy.
Engines.Count	Display	The number of engines used. This can be changed in the SysCAD configuration (.cfg) file for the project.
(The following parameters are shown for all engines (Engines column) and each individual OLI Engine in a table:)
ReloadCount	Display	The number of model reloads that have been performed. The reloads are required when an engine switches between models. It is reset to zero at the beginning of a run.
ReloadTime	Display	The cumulative amount of time that the OLI engine/s have been reloading different models.
AverageReloadTime	Display	The average amount of time required for a OLI reload. AverageReloadTime = ReloadTime/ReloadCount.
CalcCount	Display	The number of calculations that have been performed mapping the OLI species data to the SysCAD species data. The mappings are required for other units such as the OLI Side Calc Model or OLI Reactor . This is cumulative and may include multiple iterations. It is reset to zero at the beginning of a run.
CalcTime	Display	The cumulative amount of time that OLI engine/s have been performing calculations. This is cumulative and may include multiple runs.
AverageCalcTime	Display	The average amount of time required for OLI calculations. AverageCalcTime = CalcTime/CalcCount.
MaxCalcTime	Display	The maximum amount of time required for OLI calculations since the last reset of the model.
PropCalcTime	Display	The total time used to calculate stream properties by OLI.
MixingTime	Display	The total time used to calculate the properties of incoming streams to unit models by OLI.
AverageMixingTime	Display	The average amount of time used to calculate the properties of incoming streams to unit models by OLI.
MaxMixingTime	Display	The maximum amount of time used to calculate the properties of incoming streams to unit models by OLI.
LockCount	Display	The number of times the OLI engine/s are locked (is use).
LockedTime	Display	The cumulative amount of time that OLI engine/s have been locked (in use). This is cumulative and may include multiple runs.
SysCAD Solver
Iterations	Display	Total iterations since beginning of run.
SolveTime	Display	Total solve time since beginning of run.
PerIter.CalcCount	Display	The average number of OLI calculations per iteration. PerIter.CalcCount = Engines.CalcCount/Iterations.
PerIter.CalcTime	Display	The average amount of time required for OLI calculations per iteration. PerIter.CalcTime = Engines.CalcTime/Iterations.
PerIter.WaitTime	Display	The average amount of wait time per iteration. PerIter.WaitTime = Engines.WaitTime/Iterations.
PerIter.LockedTime	Display	The average amount of time the engines are locked (in use) per iteration. PerIter.LockedTime = Engines.LockedTime/Iterations.
Global list of OLIModelCfg for OLI Interface (Only available in Build 139 or later)
ModelCfgCount	Display	The number of OLI Model Configuration models in the project which are using OLI Interface Engines.
ModelCfgTagX	Display	The tag (X) for each OLIModelCfg using this Interface.

Adding this Model to a Project

Insert into Configuration file

Sort either by DLL or Group.

	DLL:	ScdOLI2.dll	→	Units/Links	→	TCE OLI: OLI Chem Model Configuration
or	Group:	General	→	Units/Links	→	TCE OLI: OLI Chem Model Configuration

See Model Selection for more information on adding models to the configuration file.

Insert into Project

Insert Unit

→

TCE OLI

→

OLI Chem Model Configuration

See Insert Unit for general information on inserting units.