`chemapp.core`

This module provides base infrastructure used in the ChemApp for Python package.

The following abbreviations are used in the interface to name functions, parameters, etc.:

Abbreviation	Term	Abbreviation	Quantity
eq	equilibrium	A	amount
cf	chemical formula	Cp	heat capacity
mm	molar mass	E	energy
ph	phase	G	Gibbs energy
phs	phases	H	enthalpy
pc	phase constituent	IA	incoming amount
pcs	phase constituents	MU	chemical potential
sc	system component	P	pressure
scs	system components	S	entropy
st	stream	T	temperature
sts	streams	V	volume
tg	target	VT	total volume
tx	transition	X	fraction
txs	transitions	XT	mole fraction
		y	mass fraction

Module Contents

Classes

`AmountUnit`	Available amount units.
`EnergyUnit`	Available energy units.
`VolumeUnit`	Available volume units.
`PressureUnit`	Available pressure units.
`TemperatureUnit`	Available temperature units.
`Quantity`	Quantities available for setting units.
`ConditionVariable`	Available variables for setting conditions in equilibrium calculations.
`InteractionVariable`	Enum to specific the type of interaction parameter to extract.
`LimitVariable`	Limit variables that can be set during target calculations.
`IoOption`	Input/output options used by `tqgio()` and
`ConfigurationOption`	Configuration options for ChemApp.
`ChemAppError`	Errors generated by the ChemApp API's standard error reporting mechanism.
`ChemAppInfo`	This class provides information about ChemApp.
`ChemAppLightError`	Errors related to ChemApp light.
`ChemicalFormulaIncomingAmountState`	This class represents the state of a chemical formula incoming amount in
`Composition`	Represents a Composition, which is essentially a {element:amount} mapping
`EquilibriumCalculationResult`	An object of this class stores all the results of a single equilbrium
`StreamCalculationResult`	See EquilibriumCalculationResult
`FunctionData`	Available data items that can be requested for functions.
`FunctionSumVariable`	Available function sum data for ChemSage.dat with functions.
`IncomingAmountState`	This abstract base class represents the state of an incoming amount in
`DataFormat`	This enumeration contains a list of data formats that ChemApp for Python objects
`PhaseConfig`	This class represents the configuration of a phase as read from a
`PhaseConstituentConfig`	This class represents the configuration of a phase constituent as read from
`PhaseConstituentData`	Available data items that can be requested for phase constituents.
`PhaseConstituentIncomingAmountState`	This class represents the state of an phase constituent incoming amount in
`PhaseConstituentState`	This class represents the state of a phase constituent in an equilibrium
`PhaseConstituentVariable`	Available variables for extracting thermodynamic properties of phase
`PhaseMapVariable`	Variables that can be used to adjust conditions as part of phase map
`PhaseMatterState`	Aggregate state of a phase.
`PhaseState`	This class represents the state of a phase in an equilibrium calculation
`ResultVariable`	Result variables available after equilibrium calculations.
`SolutionModel`	Available solution models.
`Status`	Status values for phases and phase constituents.
`StreamState`	This class represents the state of a stream used as input to a stream
`StreamVariable`	Available variables for stream properties that can be extracted.
`SystemComponentConfig`	This class represents the configuration of a system component as read from a
`SystemComponentIncomingAmountState`	This class represents the state of a system component incoming amount in
`SystemComponentState`	This class represents the state of a system component in an equilibrium
`TargetVariable`	Variables that can be used in target calculations to arrive at a specified
`ThermochemicalSystemConfig`	An object of this class stores all the information about a thermochemical
`ConvertableObject`	This class provides base infrastructure for all other classes in this

Functions

`find_state`(phase_name)	Get the physical state of a phase, guessed by the phase name.
`switch_components`(composition, components[, tol, ...])	Determine the stoichiometric factors for a composition given a set of

class chemapp.core.AmountUnit

Bases: enum.Enum

Available amount units.

Amount
mol
gram
kg
tonne
pound

class chemapp.core.EnergyUnit

Bases: enum.Enum

Available energy units.

Energy
J
cal
Btu
kWh

class chemapp.core.VolumeUnit

Bases: enum.Enum

Available volume units.

Volume
dm3
cm3
m3
ft3
in3

class chemapp.core.PressureUnit

Bases: enum.Enum

Available pressure units.

Option
bar
atm
Pa
kPa
psi
torr

class chemapp.core.TemperatureUnit

Bases: enum.Enum

Available temperature units.

Temperature
K
C
F

class chemapp.core.Quantity

Bases: enum.Enum

Quantities available for setting units.

Quantity	Unit
Pressure	bar
	atm
	Pa
	kPa
	psi
	torr
Volume	dm3
	cm3
	m3
	ft3
	in3
Temperature	K
	C
	F
Energy	J
	cal
	Btu
	kWh
Amount	mol
	gram
	kg
	tonne
	pound

class chemapp.core.ConditionVariable

Bases: enum.Enum

Available variables for setting conditions in equilibrium calculations.

Value	Variable	Description
P	Total pressure	Last entered (pressure or volume) takes precedence. Default value is 1 bar.
VT	Total volume	Last entered (pressure or volume) takes precedence. Note that the use of this option to perform calculations at constant volume is discouraged, see Appendix B.4 for details.
T	Temperature	Default value is 1000 K.
A	Amount of phase	VAL >=0 defines a formation target calculation; VAL <0 a precipitation target calculation for a mixture phase. In a formation target calculation, the target variable is varied until unit activity and zero amount of the target phase is achieved. A precipitation target is defined as one where the target phase is the only one formed at equilibrium, and the second most stable phase has unit activity.
IA	Incoming amount	Valid for phase constituents and system components. Not permitted for TQSTEC.
MU	Chemical potential	Valid only for phase constituents. Not permitted for TQSTEC.
AC	Relative activity,	Valid only for phase constituents. Not permitted for TQSTEC.
CP, H, S, G, V,	Heat capacity, Enthalpy, Entropy, Gibbs energy, Volume	Valid for the entire system or for a phase. Extensive properties are either calculated for the equilibrium phases and are then dependent on the reference state chosen in the data-file, or for the chemical reaction when streams are defined, in which case they are relative to the state defined by the stream conditions.
AT	Relative activity	Relative activity of a phase constituent as target.
XT	Mole fraction	Mole fraction of a phase constituent as target.
XPT	Mole fraction	Mole fraction of a system component in a phase as target.

class chemapp.core.InteractionVariable

Bases: enum.Enum

Enum to specific the type of interaction parameter to extract.

Option	Meaning
G	Gibbs energy function excess parameters
M	Magnetic interaction parameters

class chemapp.core.LimitVariable

Bases: enum.Enum

Limit variables that can be set during target calculations.

Option	Variable Limit	Default Value
PLOW	Low pressure limit	1E-50 bar
PHIGH	High pressure limit	1E7 bar
VLOW	Low volume limit	1E-7 dm3
VHIGH	High volume limit	1E50 dm3
TLOW	Low temperature limit	298.15 K
THIGH	High temperature limit	6000 K

class chemapp.core.IoOption

Bases: enum.Enum

Input/output options used by tqgio() and tqcio().

Option	Meaning	Default value
FILE	Unit from which the thermodynamic data-file is read	10
ERROR	Unit to which error messages are directed	6
LIST	Unit to which optional equilibrium output lists are directed	6
LANGUAGE	Language used for error messages (1=English, 2=German, 3=French, 4=Swedish, 5=Finnish)	1

class chemapp.core.ConfigurationOption

Bases: enum.Enum

Configuration options for ChemApp.

Parameters:: E – The electron configuration option.

class chemapp.core.ChemAppError

Bases: ChemAppPyError

Errors generated by the ChemApp API’s standard error reporting mechanism.

It is possible to acquire the ChemApp error number via the errno property. If this is not applicable, it will return 0.

property errno: int

<int> The error number of ChemApp, if applicable. Defaults to 0.

Return type:: int

class chemapp.core.ChemAppInfo

Bases: Object

This class provides information about ChemApp.

property array_size_descriptions: Get the array size descriptions of ChemApp’s memory setup.

property array_sizes_max: Get the maximum array sizes of ChemApp.

property array_sizes_used: Get the currently used array size descriptions of ChemApp.

property copyright: Get the copyright message of ChemApp.

property dongle_id: Get the dongle ID.

property dongle_type: Get the dongle type.

property expiration_date: Get the ChemApp expiration date.

property is_light: Get if the light version of ChemApp is used.

property program_id: Get the ChemApp program id.

property user_id: Get the user id.

property user_name: Get the user name.

property version: Get the ChemApp version.

class chemapp.core.ChemAppLightError

Bases: ChemAppPyError

Errors related to ChemApp light.

exception chemapp.core.ChemAppPyError

Bases: Exception

Base class for all errors related to the ChemApp python package.

class chemapp.core.ChemicalFormulaIncomingAmountState

Bases: IncomingAmountState

This class represents the state of a chemical formula incoming amount in an equilibrium calculation result.

Parameters:

cf (str) – chemical formula
A (float) – amount value

property A: float

Amount.

Returns:: Amount
Return type:: float

property cf: str

Chemical formula name.

Returns:: chemical formula
Return type:: str

property scs: List[str]

System components present in the chemical formula.

Returns:: System components in the chemical formula
Return type:: List[str]

property scs_A: Dict[str, float]

System components and amounts in the chemical formula.

Returns:: calculated system component amounts
Return type:: Dict[str, float]

class chemapp.core.Composition

Represents a Composition, which is essentially a {element:amount} mapping

It can be parsed from a string representation of a composition. Some examples: “Fe2O3”, “Sr(OH)3”, “H2O”, “LiPO4”.

It can also be created as a copy of another Composition class, or from a dictionary of elements:amounts mappings. For consistency reasons, the order of the elements is preserved as entered.

Parameters:: *args (str | Composition | Dict[str,float]) – The composition to create.

property elements: FrozenSet[str]

The elements the composition contains.

Returns:: element set
Return type:: FrozenSet[str]

property formula: str

String representation of the composition.

This gives the formula after internal parsing. It may be differently formatted compared to the input formula.

Examples

>>> Composition("H20").formula
'H20'

>>> Composition("Cs(OH)3").formula
'Cs1O3H3'

Returns:: printable composition
Return type:: str

property num_atoms: float

Get the number of atoms in the formula.

Returns:: sum of all constituent atom amounts
Return type:: float

property pretty_formula: str

Get the pretty formula of the composition

Elements sorted by Pauling order. No grouping of functional groups. If an element has the amount equal to 1, that number is omitted.

Returns:: printable composition
Return type:: str

property pretty_reduced_formula: str

Get the pretty reduced formula of the composition

Elements sorted by Pauling order. No grouping of functional groups. Smallest common denominator applied to the element composition.

Returns:: printable composition
Return type:: str

property reduced_formula: str

Get the reduced formula of the composition

Smallest common denominator applied to the element composition.

Returns:: printable composition
Return type:: str

property unordered: Dict[str, float]

Get the as entered order of elements.

Returns:: elemental composition
Return type:: Dict[str, float]

to_dict(reduced=False)

Get the composition as dictionary {element:amount}.

Parameters:: reduced – (default: False) Whether the smallest applicable scaling factor is applied.
Return type:: Dict[str, float]

Examples

>>> Composition("Fe4O6").to_dict()
{"Fe": 4.0, "O": 6.0}

>>> Composition("Fe4O6").to_dict(reduced=True)
{"Fe": 2.0, "O": 3.0}

Returns:: Dictionary of {element:amount} of the composition
Return type:: Dict[str, float]

class chemapp.core.EquilibriumCalculationResult

Bases: ConvertableObject

An object of this class stores all the results of a single equilbrium calculation result, regardless of the type of calculation (normal, stream, phase map).

Parameters:

units (Dict[str, PressureUnit | VolumeUnit | TemperatureUnit | EnergyUnit | AmountUnit]) – units as returned by Units.get()
ts_md5 (str) – md5 checksum of the thermochemical data file that the result is based on
t_start (float) – calculation start timestamp
t_end (float) – calculation end timestamp
dt (float) – calculation time

property IAs: List[IncomingAmountState]

The specified or calculated incoming amounts.

Returns:: incoming amounts
Return type:: List[IncomingAmountState]

property dt: float

Calculation duration.

Returns:: duration, seconds.
Return type:: float

property id: int

The result’s ID.

Returns:: result id
Return type:: int

property labels: Dict[str, str]

Labels that annotate and classify the calculation result.

Returns:: Labels
Return type:: Dict[str,str]

property phs: Dict[str, PhaseState]

The equilibrium phase states.

Returns:: phase states
Return type:: Dict[str, PhaseState]

property scs: Dict[str, SystemComponentState]

The equilibrium system component states.

Returns:: system component states
Return type:: Dict[str, PhaseState]

property t_end: float

Calculation end time.

Returns:: end time
Return type:: float

property t_start: float

Calculation start time.

Returns:: start time
Return type:: float

property ts_md5: str

The md5 checksum of the thermochemical data file that the result is based on.

Returns:: md5 hash
Return type:: float

property units: Dict[str, PressureUnit | VolumeUnit | TemperatureUnit | EnergyUnit | AmountUnit]

The units used for the calculation.

Returns:: units
Return type:: Dict[str, PressureUnit | VolumeUnit | TemperatureUnit | EnergyUnit | AmountUnit]

create_gas_stream(name, include_zeros=False)

Create a stream state object from this result object including only phases that are gasses.

Parameters:

name (str) – stream name
include_zeros (bool) – include zero values (default: False)

Returns:

new stream object

Return type:

StreamState

create_liquid_stream(name, include_zeros=False)

Create a stream state object from this result object including only phases that are liquid.

Parameters:

name (str) – stream name
include_zeros (bool) – include zero values (default: False)

Returns:

new stream object

Return type:

StreamState

create_solid_stream(name, include_zeros=False)

Create a stream state object from this result object including only phases that are solid.

Parameters:

name (str) – stream name
include_zeros (bool) – include zero values (default: False)

Returns:

new stream object

Return type:

StreamState

create_stream(name, include_zeros=False, phs_include=None, phs_exclude=None, els_include=None, els_exclude=None, phsconfigs=None, el_threshold=0.0)

Create a stream state object from this result object.

Either phs_include _or_ phs_exclude can be defined. Equally, only either els_include _or_ els_exclude can be used. If the latter is employed, the parameter phsconfig needs to be given, too. It can be acquired through ThermochemicalSystem.get_config_phs().

Parameters:

name (str) – stream name
include_zeros (bool) – include zero values
phs_include (List[str]) – phases to include
phs_exclude (List[str]) – phases to ignore
els_include (List[str]) – elements to include
els_exclude (List[str]) – elements to ignore
phsconfigs (ThermochemicalSystemConfig) – phase configurations, as returned by ThermochemicalSystem.get_config_phs()
el_threshold (float) – minimum threshold value to be considered (default: 0.0)

Returns:

new stream object

Return type:

StreamState

create_stream_by_state(state, name, include_zeros=False)

Create a stream state object from this result object including only phases that match the ‘state’.

Parameters:

state (PhaseMatterState) – phase state
name (str) – stream name
include_zeros (bool) – include zero values (default: False)

Returns:

new stream object

Return type:

StreamState

get_eq_phs(A=0.0)

Get the list of stable phases from this result object.

The criteria for stability is phase activity to be equal to 1, and the amount being larger than the given threshold A

Parameters:: A (float) – minimum threshold for a stable phase amount (default: 0.0)
Returns:: list of references to phase state objects
Return type:: List[PhaseState]

class chemapp.core.StreamCalculationResult

Bases: EquilibriumCalculationResult

See EquilibriumCalculationResult

streams()

Get the streams that are input to the equilibrium calculation.

Returns:: Streams that were input to the equilibrium calculation.
Return type:: Dict[StreamState]

class chemapp.core.FunctionData

Bases: enum.Enum

Available data items that can be requested for functions.

FunctionData	Description
H	Enthalpy
S	Entropy
Cp	Cp function coefficients
Tt	Temperature of transition
Ht	Heat of transition
V	Volume

class chemapp.core.FunctionSumVariable

Bases: enum.Enum

Available function sum data for ChemSage.dat with functions.

Option	Meaning
G	Gibbs energy function parameters
V	Volumetric expansion parameters

class chemapp.core.IncomingAmountState

Bases: Object

This abstract base class represents the state of an incoming amount in an equilibrium calculation result.

Parameters:: A (float) – amount value

property A: float

Amount.

Returns:: amount
Return type:: float

class chemapp.core.DataFormat

Bases: enum.Enum

This enumeration contains a list of data formats that ChemApp for Python objects can be converted to and from. The formats are as follows:

indexedPrimitiveDoc

A document built of primitive Python data types. The root type is a dict, and nested containers are stored as lists so that they are indexed.
mongoDbIndexedPrimitiveDoc

The same as indexedPrimitiveDoc with one exception. Dots (.) in element names are replaced with underscores to prevent query problems in MongoDB.

class chemapp.core.PhaseConfig

Bases: ObjectDescriptor

This class represents the configuration of a phase as read from a thermochemical data file.

Parameters:

index (int) – phase one-based index
name (str) – phase name
model (SolutionModel) – phase’s solution model
pcs (List[PhaseConstituentConfig]) – phase constituent configuration objects
alt_name (str) – phase’s alternative name

property alt_name: str

The phase’s alternative name.

Returns:: name
Return type:: str

property model: SolutionModel

The phase’s solution model.

Returns:: phase model
Return type:: SolutionModel

property pcs: Dict[str, PhaseConstituentState]

The equilibrium phase constituent states.

Returns:: phase constituent states
Return type:: Dict[str, PhaseConstituentState]

class chemapp.core.PhaseConstituentConfig

Bases: ObjectDescriptor

This class represents the configuration of a phase constituent as read from a file.

Parameters:

index (int) – phase constituent one-based index
name (str) – phase constituent name
mm (float) – phase constituent molar mass
stoich (Dict[str,float]) – phase constituent stoichiometry
y_scs (Dict[str,float]) – system component mass fractions

property mm: float

The phase constituent’s molar mass.

Returns:: molar mass
Return type:: float

property stoich: Dict[str, float]

The phase constituent’s stoichiometry.

Returns:: stoichiometry
Return type:: Dict[str,float]

property y_scs: Dict[str, float]

The mass fraction of system components in the constituent.

Returns:: mass fractions
Return type:: Dict[str,float]

class chemapp.core.PhaseConstituentData

Bases: enum.Enum

Available data items that can be requested for phase constituents.

OPTION	Variable
H	Enthalpy/J at 298.15K
S	Entropy/J*K-1 at 298.15K
Cp	Heat capacity expression/J.K-1 or Helgeson terms for the models PIHZ, HELZ, HTSZ, HTWZ or HTDZ
V	Molar volume data in input order of a condensed phase constituent
Gc	Critical properties in input order of a gas phase constituent
Ht	Transformation enthalpy/J at the upper temperature limit for a Cp range
M	Curie/Neel temperature and average magnetic moment per atom for a magnetic phase constituent
Tt	Upper temperature limit/K for a Cp range
Ch	Charge of an aqueous phase constituent

class chemapp.core.PhaseConstituentIncomingAmountState

Bases: IncomingAmountState

This class represents the state of an phase constituent incoming amount in an equilibrium calculation result.

Parameters:

ph (str) – phase name
pc (str) – phase constituent name
A (float) – amount value

property pc: str

Phase constituent name.

Returns:: constituent name
Return type:: str

property ph: str

Phase name.

Returns:: phase name
Return type:: str

class chemapp.core.PhaseConstituentState

Bases: ObjectDescriptor

This class represents the state of a phase constituent in an equilibrium calculation result.

Parameters:

index (int) – phase constituent one-based index
name (str) – phase constituent name
status (Status) – phase constituent status

property status: Status

The phase constituent’s status.

Returns:: phase constituent status
Return type:: Status

class chemapp.core.PhaseConstituentVariable

Bases: enum.Enum

Available variables for extracting thermodynamic properties of phase constituents.

Value	Description
CP	Heat capacity
G	Gibbs energy
H	Enthalpy
S	Entropy
T	Temperature (used to retrieve the upper limit of the current temperature interval for a given phase constituent or a stoichiometric condensed phase)
V	Volume

class chemapp.core.PhaseMapVariable

Bases: enum.Enum

Variables that can be used to adjust conditions as part of phase map calculations.

Option	Variable	Comment
PF / PN	Total pressure	Pressure is the search variable. The upper and lower bounds of the pressure search interval are in VALS(1) and VALS(2). Use option ‘PF’ for the first call to `tqmap()`, and ‘PN’ for all subsequent ones.
TF / TN	Temperature	Temperature is the search variable. The upper and lower bounds of the temperature search interval are in VALS(1) and VALS(2). Use option ‘TF’ for the first call to `tqmap()`, and ‘TN’ for all subsequent ones.
IA0 / IAF / IAN	Incoming amount	Incoming amount is the search variable. The upper and lower bounds of the composition search interval are in VALS(1) and VALS(2). If incoming amounts for more than one substance need to be defined, all except the last one have to be called using ‘IA0’ as option to `tqmap()`. Once ‘IAF’ is passed for the last incoming amount, the first calculation is made. Use option ‘IAN’ for all subsequent ones.

class chemapp.core.PhaseMatterState

Bases: enum.Enum

Aggregate state of a phase.

Option	Matter of State
SOLID	Solid
LIQUID	Liquid
GAS	Gas

class chemapp.core.PhaseState

Bases: ObjectDescriptor

This class represents the state of a phase in an equilibrium calculation result.

Parameters:

index (int) – phase one-based index
name (str) – phase name
status (Status) – phase status

property pcs: Dict[PhaseConstituentState]

The equilibrium phase constituent states.

Returns:: phase constituent states
Return type:: Dict[PhaseConstituentState]

property scs: Dict[SystemComponentState]

The equilibrium system component states.

Returns:: system component states
Return type:: Dict[SystemComponentState]

property status: Status

The phase’s status.

Returns:: phase status
Return type:: Status

class chemapp.core.ResultVariable

Bases: enum.Enum

Result variables available after equilibrium calculations.

Option	Variable	Comment
P	Total pressure	—
VT	Total volume	—
T	Temperature	—
A	Equilibrium amount	—
IA	Incoming amount	Not valid for phases or for the entire system
MU, AC	Chemical potential, Activity/fugacity	Relative values for phases and constituents; absolute values for system components; fugacities in current pressure unit for gas phase constituents.
pH, Eh	pH, Eh/V	The calculation of pH and Eh/V requires that the constituents H+ in the aqueous phase and H2 in the gas phase be present in the thermochemical data-file. If pH and Eh/V cannot be calculated, theoutput VAL=0.0 will be returned. In order for ChemApp to recognize H+ and H2 in the data-file, the names of the system components hydrogen and aqueous electron must be ‘H’ and ‘EA’, respectively (see TQCNSC).
CP, H, S, G, V,	Heat capacity, Enthalpy, Entropy, Gibbs energy, Volume	Not valid for system components. Extensive properties for the equilibrium state dependent on the inherent reference state of the data. However, when the entire system is selected and streams are used, the values represent balances, i.e. the extensive property for the equilibrium state minus the sum of values for all streams. To obtain the total volume in this case, use option ‘VT’.
CPM, HM, SM, GM, VM	Heat capacity/ amount unit, Enthalpy/ amount unit, Entropy/ amount unit, Gibbs energy/ amount unit, Volume/ amount unit	Not valid for system components. Partial values are returned for constituents, integral values for phases. Values are valid for default or selected amount units.
X	Fraction	Mass or mole fraction of a system component in the system, depending on the default or selected amount unit.
XP	Fraction	Mass or mole fraction of a system component in a phase, depending on the default or selected amount unit.
AP	Equilibrium amount	Equilibrium amount of (a) system component(s) in a phase.

class chemapp.core.SolutionModel

Bases: enum.Enum

Available solution models.

Model	Description
BDEF	Binary defect formalism
GAYE	Gaye-Kapoor-Frohberg cell formalism with or without non-oxidic solutes
HOCH	Hoch-Arpshofen formalism
HOCHM	Hoch-Arpshofen formalism with magnetism
IDBS	Gaseous model - C-H-O-S-N-Ar superfluid formalism
IDMX	Ideal mixing
IDVT	Gaseous model - Virial equation with Tsonopoulos second virial coefficient correlation
PURE	Stoichiometric condensed phase
QKTO	General polynomial Kohler/Toop formalism
QKTOM	General polynomial Kohler/Toop formalism with magnetism
QSOL	Modified quasichemical formalism with nonoxidic solutes
QUAS	Modified quasichemical formalism
QUSL	Two-sublattice equivalent fraction formalism as a polynomial
QUSLM	Two-sublattice equivalent fraction formalism as a polynomial with magnetism
RKMP	Redlich-Kister-Muggianu polynomial
RKMPM	Redlich-Kister-Muggianu polynomial with magnetism
SUBE	Extended compound energy formalism
SUBEM	Extended compound energy formalism with magnetism
SUBG	Quadruplet quasichemical model
SUBGM	Quadruplet quasichemical model with magnetism
SUBI	Two-sublattice ionic formalism
SUBL	Compound energy formalism
SUBLM	Compound energy formalism with magnetism
SUBM	Two-sublattice equivalent fraction formalism
SUBMM	Two-sublattice equivalent fraction formalism with magnetism
SUBO	Two-sublattice order/disorder formalism
SUBOM	Two-sublattice order/disorder formalism with magnetism
SUBQ	Quadruplet quasichemical model with composition-dependent coordination numbers
SUBQM	Quadruplet quasichemical model with composition-dependent coordination numbers with magnetism
SUBS	Species chemical potential/bond energy formalism
WAGN	Unified interaction parameter formalism
WAGNM	Unified interaction parameter formalism with magnetism
HELZ	Aqueous model - Revised Helgeson-Kirkham-Flowers formalism
HTDZ	Aqueous model - Helgeson-Tanger-Shock formalism (Davies)
HTSZ	Aqueous model - Helgeson-Tanger-Shock formalism (ideal)
HTWZ	Aqueous model - Helgeson-Tanger-Shock formalism (Debye-Hueckel)
IDDZ	Aqueous model - Davies formalism
IDWZ	Aqueous model - Ideal aqueous mixing
PIHZ	Aqueous model - Helgeson-Tanger-Shock formalism (Pitzer)
PIMZ	Aqueous model - Pitzer formalism
PITZ	Aqueous model - Pitzer formalism with fixed alpha-1 and alpha-2
PIWZ	Aqueous model - Pitzer formalism without E-theta and E-theta’
SITZ	Aqueous model - Specific ion-interaction formalism

class chemapp.core.Status

Bases: enum.Enum

Status values for phases and phase constituents.

Status	Description
ENTERED	The phase or constituent is included in the equilibrium calculation. An included phase is not necessarily stable at equilibrium.
DORMANT	The phase or constituent is excluded from the mass balances (it will appear with zero amount at equilibrium), but its activity is calculated. If the calculated activity for a phase is greater than one, it would be stable if entered.
ELIMINATED	The phase or constituent is ignored in the equilibrium calculation

class chemapp.core.StreamState

Bases: ConvertableObject

This class represents the state of a stream used as input to a stream equilibrium calculation (StreamCalculation).

Parameters:

name (str) – stream name
T (float) – stream temperature
P (float) – stream pressure

property A: float

Total stream amount.

Returns:: stream amount
Return type:: float

property A_pcs: List[PhaseConstituentIncomingAmountState]

Phase constituent amounts.

Returns:: phase constituent amounts
Return type:: List[PhaseConstituentIncomingAmountState]

property name: str

Stream name.

Returns:: name
Return type:: str

property units: Dict[str, PressureUnit | VolumeUnit | TemperatureUnit | EnergyUnit | AmountUnit]

The units used for the stream.

Returns:: units used
Return type:: Dict[str, PressureUnit | VolumeUnit | TemperatureUnit | EnergyUnit | AmountUnit]

combine_with(other, name='')

Add another stream’s phase constituent to this stream and return the result.

The StreamState object for which this function is called remains unchanged.

The returned Cp, H, S, G, V property is set to ‘nan’.

Parameters:

other (StreamState) – The other StreamState object to combine.
name (str) – A name for the returned new StreamState object. If empty, keep ‘self’ name.

Returns:

copy of this stream including the incoming phase amounts from ‘other’

Return type:

StreamState

remove_above_threshold(threshold=0.001, inplace=False)

Remove all phase constituents with amounts above the given threshold.

Parameters:

threshold (float) – the threshold for removal (default=0.001)
inplace (bool) – whether a copy should be returned or the object itself is modified (default=False)

Returns:

object with the phase constituents below the given threshold

Return type:

StreamState

remove_below_threshold(threshold=0.001, inplace=False)

Remove all phase constituents with amounts below the given threshold.

Parameters:

threshold (float) – the threshold for removal (default=0.001)
inplace (bool) – whether a copy should be returned or the object itself is modified (default=False)

Returns:

object with the phase constituents above the given threshold.

Return type:

StreamState

split_at_threshold(threshold=0.001)

Split a stream into two streams.

The two streams will be named <name>_lower and <name>_higher, with respect to phase constituent amounts and given threshold.

Parameters:: threshold (float) – value at which to split (default=0.001)
Returns:: tuple of StreamState. All phase constituents with amounts below threshold are in the first item.
Return type:: Tuple[StreamState, StreamState]

split_by_states()

Split a stream into three streams named <name>_liquid, <name>_solid, <name>_gas by their respective state of matter.

Returns:: (solids, liquids, gaseous) tuple of StreamState with the respective matter of state.
Return type:: Tuple[StreamState, StreamState, StreamState]

class chemapp.core.StreamVariable(*args, **kwds)

Bases: enum.Enum

Available variables for stream properties that can be extracted.

Option	Variable	Unit
Option	Variable	Unit
CP	Heat capacity	[current energy unit]/K
CP	Heat capacity	[current energy unit]/K
H	Enthalpy	[current energy unit]
H	Enthalpy	[current energy unit]
S	Entropy	[current energy unit]/K
S	Entropy	[current energy unit]/K
G	Gibbs energy	[current energy unit]
G	Gibbs energy	[current energy unit]
V	Volume	[current volume unit]
V	Volume	[current volume unit]

class chemapp.core.SystemComponentConfig

Bases: ObjectDescriptor

This class represents the configuration of a system component as read from a file.

Parameters:

index (int) – system component one-based index
name (str) – system component name
mm (float) – system component molar mass

property mm: float

The system component’s molar mass.

Returns:: molar mass
Return type:: float

class chemapp.core.SystemComponentIncomingAmountState

Bases: IncomingAmountState

This class represents the state of a system component incoming amount in an equilibrium calculation result.

Parameters:

sc (str) – system component name
A (float) – amount value

property sc: str

System component name.

Returns:: name
Return type:: str

class chemapp.core.SystemComponentState

Bases: ObjectDescriptor

This class represents the state of a system component in an equilibrium calculation result.

Parameters:

index (int) – phase one-based index
name (str) – phase name

class chemapp.core.TargetVariable

Bases: enum.Enum

Variables that can be used in target calculations to arrive at a specified target condition.

Option	Variable	Description
P	Total pressure	Pressure is a target variable. The value VALS(1) serves as an initial estimate, VALS(2) is not used.
V	Total volume	Volume is a target variable. The value VALS(1) serves as an initial estimate, VALS(2) is not used.
T	Temperature	Temperature is a target variable. The value VALS(1) serves as an initial estimate, VALS(2) is not used.
IA, IA0, MU	Incoming amount, Chemical potential	Incoming amount is a target variable. The values VALS(1) and VALS(2) denote lower and upper limits, respectively. When defining streams, the constituent is included in the last stream considered. If incoming amounts for more then one substance need to be defined, all except the last one have to be called using ‘IA0’ as option to TQCE/TQCEL. Once ‘IA’ is passed for the last incoming amount, the first calculation is made.
Blank		Calculate without any target variable, VALS is not used.

class chemapp.core.ThermochemicalSystemConfig

Bases: ConvertableObject

An object of this class stores all the information about a thermochemical system as it is read from a thermochemical data file.

Parameters:

file_path (str) – the path of the thermochemical data file
file_expiry_date (float) – the thermochemical data file expiry date
units (Dict[str, PressureUnit | VolumeUnit | TemperatureUnit | EnergyUnit | AmountUnit]) – the units on which this object is based

property file_content: str

The binary content of the thermochemical data file from which the thermochemical system was loaded.

Return type:: str

property file_expiry_date: float

The expiry date of the thermochemical data file from which the thermochemical system was loaded.

Return type:: float

property file_md5: str

The MD5 hash of the thermochemical data file from which the thermochemical system was loaded.

Return type:: str

property file_name: str

The name of the thermochemical data file from which the thermochemical system was loaded.

Return type:: str

property file_path: str

The path of the thermochemical data file from which the thermochemical system was loaded.

Return type:: str

property phs: Dict[str, PhaseConfig]

Dictionary of phases.

Return type:: Dict[str, PhaseConfig]

property scs: Dict[str, SystemComponentConfig]

Dictionary of system components.

Return type:: Dict[str, SystemComponentConfig]

property units: Dict[str, PressureUnit | VolumeUnit | TemperatureUnit | EnergyUnit | AmountUnit]

The ChemApp units that were active when this object was created.

All numbers stored in this object and its child objects are in these units.

Return type:: Dict[str, PressureUnit | VolumeUnit | TemperatureUnit | EnergyUnit | AmountUnit]

chemapp.core.find_state(phase_name)

Get the physical state of a phase, guessed by the phase name.

Typically, e.g. liquid phase descriptions of ‘compounds’ are indicated by the phase name ending in _l or _(l). Similarly, gaseous species are very likely to be named _g or _(g). This function uses these and more assumptions to guess the state of a phase.

Notice that matter of state is not a set property of the thermodynamic datafiles, and therefore only (educated) guesses are possible. If unsure, a phase name is assumed to be condensed/solid.

Returns:: The likely state of the phase.
Return type:: PhaseMatterState
Parameters:: phase_name (str) –

chemapp.core.switch_components(composition, components, tol=1e-05, normalize=False)

Determine the stoichiometric factors for a composition given a set of arbitrary components.

This function returns the numeric factors needed to create composition from the list of chemical formulae given in components.

Parameters:

composition (str) – chemical formulae of the composition to be decomposed
components (List[str]) – components which are linearly combined to form composition
tol (float) – tolerance value for matching exact stoichiometries (default=1e-5)
normalize (bool) – scale the sum of stoichiometric factors to 1 (default=false)

Return type:

List[float]

Examples

>>> switch_components("Fe3O4", ["FeO", "O2"])
[3.0, 2.0]

>>> switch_components("SrNaCl3", ["NaCl", "SrCl2"])
[1.0, 1.0]

>>> switch_components("SrNaCl3", ["NaCl", "Sr", "Cl"])
[1.0, 1.0, 2.0]

Notice that the method uses a least square method internally to find a solution. Therefore, it is not necessary for the components to be orthogonal to each other, e.g. one component can be a linear combination of others.

>>> switch_components("SrNaCl3", ["NaCl", "Cl2","Sr", "Cl"])
[1.0, 0.8, 1.0, 0.4]

However, in that case the solution is obviously not unique. Using the “normalize” option will not change that.

>>> switch_components("Fe3O4", ["FeO", "O2"], normalize=True)
[0.8571.., 0.1428..]

Using the tol option allows to approximate factors, e.g. in case of non-integer component compositions:

>>> switch_components("Al2O5", ["Al1.125O", "O"], tol=1e-2)
[1.78, 3.22]

Returns:

The stoichiometric factors for components that will form composition

Return type:

List[float]

Raises:

ValueError – In case there does not exist a rational positive solution given the inputs.

Parameters:

composition (str) –
components (List[str]) –
tol (float) –
normalize (bool) –

class chemapp.core.ConvertableObject

Bases: Object

This class provides base infrastructure for all other classes in this module.

classmethod create_from(src, format=..., **kwargs)

Create an object from the specified source.

Parameters:

format (DataFormat) – the data format to use
src – the source object
kwargs – dictionary of optional keyword arguments

Returns:

instance of this class

Return type:

ConvertableObject

convert_to(format=...)

Convert this object to an object of the specified format.

Parameters:: format (DataFormat) – the data format to use (DataFormat enumeration)
Returns:: an object in the specified format
Return type:: ConvertableObject

chemapp.core

Module Contents

Classes

Functions

`chemapp.core`