Module “batch_equilibrium”¶

class tc_python.batch_equilibrium.BatchEquilibriumCalculation(calculator)¶

Bases: AbstractCalculation

Configuration for a series of single equilibrium calculations performed in a vectorized fashion.

Note

Specify the conditions and call calculate().

Tip

The performance of batch equilibrium calculations can be significantly better than looping and using SingleEquilibriumCalculation if the actual Thermo-Calc calculation is fast. There is little advantage if the Thermo-Calc equilibrium calculations take a long time (typically for large systems and databases).

calculate(quantities: List[Union[ThermodynamicQuantity, str]], logging_frequency: int = 10, timeout_in_minutes: float = 0.0) → BatchEquilibriumResult¶

Runs the batch equilibrium calculation. The calculated BatchEquilibriumResult can then be queried for the values of the quantities specified.

Example:

>>> quantities = ['G', 'X(BCC)']

Parameters:

quantities – A list of the quantities to be calculated.
logging_frequency – Determines how often logging should be done.
timeout_in_minutes – Used to prevent the calculation from running longer than what is wanted, or from hanging. If the calculation runs longer than timeout_in_minutes, a UnrecoverableCalculationException will be thrown, the current TCPython-block will be unusable and a new TCPython block must be created for further calculations.

Returns:

A BatchEquilibriumResult which later can be used to get specific values from the calculated result.

disable_global_minimization()¶

Turns the global minimization completely off.

Returns:: This BatchEquilibriumCalculation object

enable_global_minimization()¶

Turns the global minimization on (using the default settings).

Returns:: This BatchEquilibriumCalculation object

get_components() → List[str]¶

Returns a list of components in the system (including all components auto-selected by the database(s)).

Returns:: The components

get_gibbs_energy_addition_for(phase: str) → float¶

Used to get the additional energy term (always being a constant) of a given phase. The value given is added to the Gibbs energy of the (stoichiometric or solution) phase. It can represent a nucleation barrier, surface tension, elastic energy, etc.

It is not composition-, temperature- or pressure-dependent.

Parameters:: phase – Specify the name of the (stoichiometric or solution) phase with the addition
Returns:: Gibbs energy addition to G per mole formula unit.

get_system_data() → SystemData¶

Returns the content of the database for the currently loaded system. This can be used to modify the parameters and functions and to change the current system by using with_system_modifications().

Note

Parameters can only be read from unencrypted (i.e. user) databases loaded as *.tdb-file.

Returns:: The system data

remove_all_conditions()¶

Removes all set conditions.

Returns:: This BatchEquilibriumCalculation object

remove_condition(quantity: Union[ThermodynamicQuantity, str])¶

Removes the specified condition.

Parameters:: quantity – the thermodynamic quantity to set as condition; a Console Mode syntax string can be used as an alternative (for example “X(Cr)”)
Returns:: This BatchEquilibriumCalculation object

run_poly_command(command: str)¶

Runs a Thermo-Calc command from the Console Mode POLY module immediately in the engine.

Parameters:: command – The Thermo-Calc Console Mode command
Returns:: This BatchEquilibriumCalculation object

Note

It should not be necessary for most users to use this method, try to use the corresponding method implemented in the API instead.

Warning

As this method runs raw Thermo-Calc commands directly in the engine, it may hang the program in case of spelling mistakes (e.g. forgotten equals sign).

set_component_to_entered(component: str)¶

Sets the specified component to the status ENTERED, that is the default state.

Parameters:: component – The component name or ALL_COMPONENTS
Returns:: This BatchEquilibriumCalculation object

set_component_to_suspended(component: str, reset_conditions: bool = False)¶

Sets the specified component to the status SUSPENDED, i.e. it is ignored in the calculation.

Parameters:

reset_conditions – if ‘True’ also remove composition conditions for the component if they are defined
component – The component name or ALL_COMPONENTS

Returns:

This BatchEquilibriumCalculation object

set_condition(quantity: Union[ThermodynamicQuantity, str], value: float)¶

Sets the specified condition.

Parameters:

quantity – The thermodynamic quantity to set as condition; a Console Mode syntax string can be used as an alternative (for example “X(Cr)”)
value – The value of the condition

Returns:

This BatchEquilibriumCalculation object

set_conditions_for_equilibria(equilibria: List[List[Tuple[Union[ThermodynamicQuantity, str], float]]])¶

Set the conditions of the equilibria to be calculated.

This is done by sending a list of equilibria at once.

Each equilibrium itself is a list of conditions that will be changed for that equilibrium.

A condition is described by a tuple containing:

A Console Mode syntax string or a ThermodynamicQuantity instance,

A float value specifying the value of the condition.

Example:

>>> [[('T', 800), ('X(Cr)', 0.1)], [('T', 850), ('X(Cr)', 0.11)]]

You can use ThermodynamicQuantity instead of a Console Mode syntax string when specifying type of condition.

Example:

>>> [[(ThermodynamicQuantity.temperature(), 800), (ThermodynamicQuantity.mole_fraction_of_a_component('Cr'), 0.1)], [(ThermodynamicQuantity.temperature(), 850), (ThermodynamicQuantity.mole_fraction_of_a_component('Cr'), 0.15)]]

Parameters:: equilibria – The list of equilibria
Returns:: This BatchEquilibriumCalculation object

set_gibbs_energy_addition_for(phase: str, gibbs_energy: float)¶

Used to specify the additional energy term (always being a constant) of a given phase. The value (gibbs_energy) given is added to the Gibbs energy of the (stoichiometric or solution) phase. It can represent a nucleation barrier, surface tension, elastic energy, etc.

It is not composition-, temperature- or pressure-dependent.

Parameters:

phase – Specify the name of the (stoichiometric or solution) phase with the addition
gibbs_energy – Addition to G per mole formula unit

Returns:

This BatchEquilibriumCalculation object

set_phase_to_dormant(phase: str)¶

Sets the phase to the status DORMANT, necessary for calculating the driving force to form the specified phase.

Parameters:: phase – The phase name or ALL_PHASES for all phases
Returns:: This BatchEquilibriumCalculation object

set_phase_to_entered(phase: str, amount: float = 1.0)¶

Sets the phase to the status ENTERED, that is the default state.

Parameters:

phase – The phase name or ALL_PHASES for all phases
amount – The phase fraction (between 0.0 and 1.0)

Returns:

This BatchEquilibriumCalculation object

set_phase_to_fixed(phase: str, amount: float)¶

Sets the phase to the status FIXED, i.e. it is guaranteed to have the specified phase fraction after the calculation.

Parameters:

phase – The phase name
amount – The fixed phase fraction (between 0.0 and 1.0)

Returns:

This BatchEquilibriumCalculation object

set_phase_to_suspended(phase: str)¶

Sets the phase to the status SUSPENDED, i.e. it is ignored in the calculation.

Parameters:: phase – The phase name or ALL_PHASES for all phases
Returns:: This BatchEquilibriumCalculation object

with_options(options: SingleEquilibriumOptions)¶

Sets the simulation options.

Parameters:: options – The simulation options
Returns:: This BatchEquilibriumCalculation object

with_reference_state(component: str, phase: str = 'SER', temperature: float = -1.0, pressure: float = 100000.0)¶

The reference state for a component is important when calculating activities, chemical potentials and enthalpies and is determined by the database being used. For each component the data must be referred to a selected phase, temperature and pressure, i.e. the reference state.

All data in all phases where this component dissolves must use the same reference state. However, different databases can use different reference states for the same element/component. It is important to be careful when combining data obtained from different databases.

By default, activities, chemical potentials and so forth are computed relative to the reference state used by the database. If the reference state in the database is not suitable for your purposes, use this command to set the reference state for a component using SER, i.e. the Stable Element Reference (which is usually set as default for a major component in alloys dominated by the component). In such cases, the temperature and pressure for the reference state is not needed.

For a phase to be usable as a reference for a component, the component needs to have the same composition as an end member of the phase. The reference state is an end member of a phase. The selection of the end member associated with the reference state is only performed once this command is executed.

If a component has the same composition as several end members of the chosen reference phase, then the end member that is selected at the specified temperature and pressure will have the lowest Gibbs energy.

Parameters:

component – The name of the element must be given.
phase – Name of a phase used as the new reference state. Or SER for the Stable Element Reference.
temperature – The Temperature (in K) for the reference state. Or CURRENT_TEMPERATURE which means that the current temperature is used at the time of evaluation of the reference energy for the calculation.
pressure – The Pressure (in Pa) for the reference state.

Returns:

This BatchEquilibriumCalculation object

with_system_modifications(system_modifications: SystemModifications)¶

Updates the system of this calculator with the supplied system modification (containing new phase parameters and system functions).

Note

This is only possible if the system has been read from unencrypted (i.e. user) databases loaded as a *.tdb-file.

Parameters:: system_modifications – The system modification to be performed
Returns:: This BatchEquilibriumCalculation object

class tc_python.batch_equilibrium.BatchEquilibriumResult(result)¶

Bases: object

Result of a batch equilibrium calculation. This can be used to query for specific values.

get_values_of(quantity: Union[ThermodynamicQuantity, str]) → List[float]¶

Returns values from a batch equilibrium calculation.

Warning

The quantity must be one of the quantities specified for the BatchEquilibriumCalculation object that created the result object.

Example:

>>> batch_result = batch_calculation.calculate(quantities = ['G', 'X(BCC)'])
>>> batch_result.get_values_of('G')

Parameters:: quantity – the thermodynamic quantity to get the value of; a Console Mode syntax strings can be used as an alternative (for example “NPM(FCC_A1)”)

invalidate()¶: Invalidates the object and frees the disk space used by it.

Note

This is only required if the disk space occupied by the object needs to be released during the calculation. No data can be retrieved from the object afterwards.