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