Module “single_equilibrium”¶

class tc_python.single_equilibrium.AbstractSingleEquilibriumCalculation(calculator)¶

Bases: tc_python.abstract_base.AbstractCalculation

Abstract configuration required for a single equilibrium calculation.

Note

This is an abstract class that cannot be used directly.

abstract calculate() → tc_python.single_equilibrium.SingleEquilibriumTempResult ¶

disable_global_minimization()¶

Turns the global minimization completely off.

Returns: This SingleEquilibriumCalculation object

enable_global_minimization()¶

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

Returns: This SingleEquilibriumCalculation 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() → tc_python.abstract_base.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

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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation object

with_options(options: tc_python.single_equilibrium.SingleEquilibriumOptions)¶

Sets the simulation options.

Parameters: options – The simulation options
Returns: This SingleEquilibriumCalculation 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 SingleEquilibriumCalculation object

with_system_modifications(system_modifications: tc_python.abstract_base.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 SingleEquilibriumCalculation object

class tc_python.single_equilibrium.SingleEquilibriumCalculation(calculator)¶

Bases: tc_python.single_equilibrium.AbstractSingleEquilibriumCalculation

Configuration for a single equilibrium calculation.

Note

Specify the conditions and possibly other settings, the calculation is performed with calculate().

bookmark_state(bookmark_id: str = '') → str¶

Puts a “bookmark” on the current calculation-state of the calculator allowing the program to return to this state later as needed.

By bookmarking a state, you can simplify the convergence of equilibria when they strongly depend on the starting conditions (i.e. the state). Also use it to improve performance by running a calculation, then bookmarking it, and later returning to it for other equilibria whose conditions are “close” to the bookmarked equilibrium.

This method is used in combination with the method set_state_to_bookmark().

Parameters: bookmark_id – The bookmark id. If omitted a generated id is used and returned
Returns: The bookmark id

calculate() → tc_python.single_equilibrium.SingleEquilibriumTempResult ¶

Performs the calculation and provides a temporary result object that is only valid until something gets changed in the calculation state. The method calculate() is the default approach and should be used in most cases.

Returns: A new SingleEquilibriumTempResult object which can be used to get specific values from the calculated result. It is undefined behavior to use that object after the state of the calculation has been changed.

Warning

If the result object should be valid for the whole program lifetime, use calculate_with_state() instead.

calculate_with_state() → tc_python.single_equilibrium.SingleEquilibriumResult ¶

Performs the calculation and provides a result object that reflects the present state of the calculation during the whole lifetime of the object.

Note

Because this method has performance and temporary disk space overhead (i.e. it is resource heavy), only use it when it is necessary to access the result object after the state is changed. In most cases you should use the method calculate().

Returns: A new SingleEquilibriumResult object which can be used later at any time to get specific values from the calculated result.

disable_global_minimization()¶

Turns the global minimization completely off.

Returns: This SingleEquilibriumCalculation object

enable_global_minimization()¶

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

Returns: This SingleEquilibriumCalculation 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_interfacial_energy(matrix_phase: str, precipitate_phases: List[str], zero_volume_elements: List[str] = ['C', 'N']) → Dict[str, float]¶

Estimates the interfacial energy between a matrix phase and a precipitate phase using thermodynamic data from a CALPHAD database. The approximation model is based on Becker’s bond energy approach.

Default: elements with no contribution to volume are C and N.

Parameters

matrix_phase – The matrix phase.
precipitate_phases – The list of precipitate phases for which interfacial energy between them and the matrix phase is to be calculated.
zero_volume_elements – The elements that are assumed to not contribute to the volume.

Returns

A dictionary containing interfacial energy per precipitate phase.

get_system_data() → tc_python.abstract_base.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 SingleEquilibriumCalculation object

remove_condition(quantity: Union[tc_python.quantity_factory.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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation object

set_condition(quantity: Union[tc_python.quantity_factory.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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation 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 SingleEquilibriumCalculation object

set_state_to_bookmark(bookmark_id: str) → tc_python.single_equilibrium.SingleEquilibriumTempResult ¶

Resets the calculation state to a previously bookmarked state.

After calling this method, the calculation behaves exactly as it would after the bookmarked calculation ran.

This method is used in combination with the method bookmark_state().

Parameters: bookmark_id – The bookmark id of the state to return to.
Returns: A new SingleEquilibriumTempResult object which can be used to get specific values from the calculated result. It is undefined behavior to use that object after the state of the calculation has been changed.

with_options(options: tc_python.single_equilibrium.SingleEquilibriumOptions)¶

Sets the simulation options.

Parameters: options – The simulation options
Returns: This SingleEquilibriumCalculation 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 SingleEquilibriumCalculation object

with_system_modifications(system_modifications: tc_python.abstract_base.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 SingleEquilibriumCalculation object

class tc_python.single_equilibrium.SingleEquilibriumOptions¶

Bases: object

General simulation conditions for the thermodynamic calculations.

disable_approximate_driving_force_for_metastable_phases()¶

Disables the approximation of the driving force for metastable phases.

Default: Enabled

Note

When enabled, the metastable phases are included in all iterations. However, these may not have reached their most favorable composition and thus their driving forces may be only approximate.

If it is important that these driving forces are correct, use disable_approximate_driving_force_for_metastable_phases() to force the calculation to converge for the metastable phases.

Returns: This SingleEquilibriumOptions object

disable_control_step_size_during_minimization()¶

Disables stepsize control during minimization (non-global).

Default: Enabled

Returns: This SingleEquilibriumOptions object

disable_force_positive_definite_phase_hessian()¶

Disables forcing of positive definite phase Hessian. This determines how the minimum of an equilibrium state in a normal minimization procedure (non-global) is reached. For details, search the Thermo-Calc documentation for “Hessian minimization”.

Default: Enabled

Returns: This SingleEquilibriumOptions object

enable_approximate_driving_force_for_metastable_phases()¶

Enables the approximation of the driving force for metastable phases.

Default: Enabled

Note

When enabled, the metastable phases are included in all iterations. However, these may not have reached their most favorable composition and thus their driving forces may be only approximate.

If it is important that these driving forces are correct, use disable_approximate_driving_force_for_metastable_phases() to force the calculation to converge for the metastable phases.

Returns: This SingleEquilibriumOptions object

enable_control_step_size_during_minimization()¶

Enables stepsize control during normal minimization (non-global).

Default: Enabled

Returns: This SingleEquilibriumOptions object

enable_force_positive_definite_phase_hessian()¶

Enables forcing of positive definite phase Hessian. This determines how the minimum of an equilibrium state in a normal minimization procedure (non-global) is reached. For details, search the Thermo-Calc documentation for “Hessian minimization”.

Default: Enabled

Returns: This SingleEquilibriumOptions object

set_global_minimization_max_grid_points(max_grid_points: int = 2000)¶

Sets the maximum number of grid points in global minimization. Only applicable if global minimization is actually used.

Default: 2000 points

Parameters: max_grid_points – The maximum number of grid points
Returns: This SingleEquilibriumOptions object

set_max_no_of_iterations(max_no_of_iterations: int = 500)¶

Set the maximum number of iterations.

Default: max. 500 iterations

Note

As some models give computation times of more than 1 CPU second/iteration, this number is also used to check the CPU time and the calculation stops if 500 CPU seconds/iterations are used.

Parameters: max_no_of_iterations – The max. number of iterations
Returns: This SingleEquilibriumOptions object

set_required_accuracy(accuracy: float = 1e-06)¶

Sets the required relative accuracy.

Default: 1.0E-6

Note

This is a relative accuracy, and the program requires that the relative difference in each variable must be lower than this value before it has converged. A larger value normally means fewer iterations but less accurate solutions. The value should be at least one order of magnitude larger than the machine precision.

Parameters: accuracy – The required relative accuracy
Returns: This SingleEquilibriumOptions object

set_smallest_fraction(smallest_fraction: float = 1e-12)¶

Sets the smallest fraction for constituents that are unstable.

It is normally only in the gas phase that you can find such low fractions.

The default value for the smallest site-fractions is 1E-12 for all phases except for IDEAL phase with one sublattice site (such as the GAS mixture phase in many databases) for which the default value is always as 1E-30.

Parameters: smallest_fraction – The smallest fraction for constituents that are unstable
Returns: This SingleEquilibriumOptions object

class tc_python.single_equilibrium.SingleEquilibriumResult(result)¶

Bases: tc_python.abstract_base.AbstractResult

Result of a single equilibrium calculation, it can be evaluated using a Quantity or Console Mode syntax.

change_pressure(pressure: float)¶

Change the pressure and re-evaluate the results from the equilibrium without minimizing Gibbs energy, i.e. with higher performance. The properties are calculated at the new pressure using the phase amount, temperature and composition of phases from the initial equilibrium. Use get_value_of() to obtain them.

Parameters: pressure – The pressure [Pa]
Returns: This SingleEquilibriumCalculation object

change_temperature(temperature: float)¶

Change the temperature and re-evaluate the results from the equilibrium without minimizing Gibbs energy, i.e. with high performance. The properties are calculated at the new temperature using the phase amount, pressure and composition of phases from the initial equilibrium. Use get_value_of() to obtain them.

Note

This is typically used when calculating room temperature properties (e.g. density) for a material when it is assumed that the equilibrium phase amount and composition freeze-in at a higher temperature during cooling.

Parameters: temperature – The temperature [K]
Returns: This SingleEquilibriumCalculation object

get_components() → List[str]¶

Returns the names of the components selected in the system (including any components auto-selected by the database(s)).

Returns: The names of the selected components

get_conditions() → List[str]¶

Returns the conditions.

Returns: The selected conditions

get_phases() → List[str]¶

Returns the phases present in the system due to its configuration. It also contains all phases that have been automatically added during the calculation, this is the difference to the method System.get_phases_in_system().

Returns: The names of the phases in the system including automatically added phases

get_stable_phases() → List[str]¶

Returns the stable phases (i.e. the phases present in the current equilibrium).

Returns: The names of the stable phases

get_value_of(quantity: Union[tc_python.quantity_factory.ThermodynamicQuantity, str]) → float¶

Returns a value from a single equilibrium calculation.

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)”)
Returns: The requested value

run_poly_command(command: str)¶

Runs a Thermo-Calc command from the Console Mode POLY module immediately in the engine. This affects only the state of the result object.

Parameters: command – The Thermo-Calc Console Mode command
Returns: This SingleEquilibriumCalculation 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).

save_to_disk(path: str)¶

Saves the result to disk. Note that the result is a folder, containing potentially many files. The result can later be loaded with load_result_from_disk()

Parameters: path – the path to the folder you want the result to be saved in. It can be relative or absolute.
Returns: this SingleEquilibriumResult object

class tc_python.single_equilibrium.SingleEquilibriumTempResult(result)¶

Bases: tc_python.abstract_base.AbstractResult

Result of a single equilibrium calculation that is only valid until something gets changed in the calculation state. It can be evaluated using a Quantity or Console Mode syntax.

Warning

Note that it is undefined behavior to use that object after something has been changed in the state of the calculation, this will result in an InvalidResultStateException exception being raised.

change_pressure(pressure: float)¶

Change the pressure and re-evaluate the results from the equilibrium without minimizing Gibbs energy, i.e. with higher performance. The properties are calculated at the new pressure using the phase amount, temperature and composition of phases from the initial equilibrium. Use get_value_of() to obtain them.

Parameters: pressure – The pressure [Pa]
Returns: This SingleEquilibriumCalculation object

change_temperature(temperature: float)¶

Change the temperature and re-evaluate the results from the equilibrium without minimizing Gibbs energy, i.e. with high performance. The properties are calculated at the new temperature using the phase amount, pressure and composition of phases from the initial equilibrium. Use get_value_of() to obtain them.

Note

This is typically used when calculating room temperature properties (e.g. density) for a material when it is assumed that the equilibrium phase amount and composition freeze-in at a higher temperature during cooling.

Parameters: temperature – The temperature [K]
Returns: This SingleEquilibriumCalculation object

get_components() → List[str]¶

Returns the names of the components selected in the system (including any components auto-selected by the database(s)).

Returns: The names of the selected components
Raises: InvalidResultStateException – If something has been changed in the state of the calculation since that result object has been created

get_conditions() → List[str]¶

Returns the conditions.

Returns: List containing the selected conditions
Raises: InvalidResultStateException – If something has been changed in the state of the calculation since that result object has been created

get_phases() → List[str]¶

Returns the phases present in the system due to its configuration. It also contains all phases that have been automatically added during the calculation, this is the difference to the method System.get_phases_in_system().

Returns: The names of the phases in the system including automatically added phases
Raises: InvalidResultStateException – If something has been changed in the state of the calculation since that result object has been created

get_stable_phases() → List[str]¶

Returns the stable phases (i.e. the phases present in the current equilibrium).

Returns: The names of the stable phases
Raises: InvalidResultStateException – If something has been changed in the state of the calculation since that result object has been created

get_value_of(quantity: Union[tc_python.quantity_factory.ThermodynamicQuantity, str]) → float¶

Returns a value from a single equilibrium calculation.

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)”)
Returns: The requested value
Raises: InvalidResultStateException – If something has been changed in the state of the calculation since that result object has been created

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 SingleEquilibriumCalculation 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).