Module “material_to_material”

class tc_python.material_to_material.AbstractConstantCondition

Bases: object

The abstract base class for all constant conditions.

class tc_python.material_to_material.AbstractMaterialToMaterialCalculationAxis

Bases: object

The abstract base class of all calculation axis.

class tc_python.material_to_material.ConstantCondition

Bases: AbstractConstantCondition

A constant condition.

classmethod fraction_of_material_b(fraction_of_material_b: float = 0.5)

Creates a constant fraction of material B condition object.

Note

The unit depends on the composition unit setting in the calculator object.

Parameters

fraction_of_material_b – The fraction of material B [weight-fraction or mole-fraction]

Returns

The condition object

classmethod temperature(temperature: float = 1000)

Creates a constant temperature condition object.

Parameters

temperature – The temperature [K]

Returns

The condition object

class tc_python.material_to_material.FractionOfMaterialBAxis(from_fraction: float = 0.0, to_fraction: float = 1.0, start_fraction: float = 0.5)

Bases: MaterialToMaterialCalculationAxis

A fraction of material B axis.

class tc_python.material_to_material.FractionOfMaterialBCondition(fraction_of_material_b: float = 0.5)

Bases: ConstantCondition

A constant fraction of material B condition.

class tc_python.material_to_material.MaterialToMaterialCalculationAxis

Bases: AbstractMaterialToMaterialCalculationAxis

A calculation axis.

classmethod fraction_of_material_b(from_fraction: float = 0.0, to_fraction: float = 1.0, start_fraction: float = 0.5)

Creates a fraction of material B axis object.

Note

The unit depends on the composition unit setting in the calculator.

Parameters
  • from_fraction – The left axis limit [weight-fraction or mole-fraction]

  • to_fraction – The right axis limit [weight-fraction or mole-fraction]

  • start_fraction – The start fraction of the calculation [weight-fraction or mole-fraction]

Returns

A new FractionOfMaterialBAxis axis object

classmethod temperature(from_temperature: float = 1000, to_temperature: float = 3000, start_temperature: float = 2000)

Creates a temperature calculation axis object.

Parameters
  • from_temperature – The left axis limit [K]

  • to_temperature – The right axis limit [K]

  • start_temperature – The start temperature of the calculation [K]

Returns

A new TemperatureAxis condition object

class tc_python.material_to_material.MaterialToMaterialCalculationContainer(instance)

Bases: object

Provides access to the calculation objects for all Material to Material calculations.

These are specialised calculations for mixtures of two materials A and B. Otherwise they behave identical to the corresponding regular single equilibrium, property diagram and phase diagram calculations.

with_phase_diagram_calculation(default_conditions: bool = True, components: List[str] = []) MaterialToMaterialPhaseDiagramCalculation

Creates a Material to Material phase diagram (map) calculation.

Parameters
  • default_conditions – If True, automatically sets the conditions N=1 and P=100000

  • components – Specify here the components of the system (for example: [AL2O3, …]), only necessary if they differ from the elements. If this option is used, all elements of the system need to be replaced by a component.

Returns

A new MaterialToMaterialPhaseDiagramCalculation object

with_property_diagram_calculation(default_conditions: bool = True, components: List[str] = []) MaterialToMaterialPropertyDiagramCalculation

Creates a Material to Material property diagram (step) calculation.

Parameters
  • default_conditions – If True, automatically sets the conditions N=1 and P=100000

  • components – Specify here the components of the system (for example: [AL2O3, …]), only necessary if they differ from the elements. If this option is used, all elements of the system need to be replaced by a component.

Returns

A new MaterialToMaterialPropertyDiagramCalculation object

with_single_equilibrium_calculation(default_conditions: bool = True, components: List[str] = []) MaterialToMaterialSingleEquilibriumCalculation

Creates a Material to Material single equilibrium calculation.

Parameters
  • default_conditions – If True, automatically sets the conditions N=1 and P=100000

  • components – Specify here the components of the system (for example: [AL2O3, …]), only necessary if they differ from the elements. If this option is used, all elements of the system need to be replaced by a component.

Returns

A new MaterialToMaterialSingleEquilibriumCalculation object

class tc_python.material_to_material.MaterialToMaterialPhaseDiagramCalculation(calculator)

Bases: AbstractPhaseDiagramCalculation

Configuration for a Material to Material phase diagram calculation.

Note

Specify the conditions, the calculation is performed with calculate().

add_initial_equilibrium(initial_equilibrium: InitialEquilibrium)

Add initial equilibrium start points from which a phase diagram is calculated.

Scans along the axis variables and generates start points when the scan procedure crosses a phase boundary.

It may take a little longer to execute than using the minimum number of start points, as some lines may be calculated more than once. But the core remembers all node points and subsequently stops calculations along a line when it finds a known node point.

It is also possible to create a sequence of start points from one initial equilibria.

Parameters

initial_equilibrium – The initial equilibrium

Returns

This MaterialToMaterialPhaseDiagramCalculation object

calculate(keep_previous_results: bool = False, timeout_in_minutes: float = 0.0) MaterialToMaterialPhaseDiagramResult

Performs the phase diagram calculation.

Warning

If you use keep_previous_results=True, you must not use another calculator or even get results in between the calculations using calculate(). Then the previous results will actually be lost.

Parameters
  • keep_previous_results – If True, results from any previous call to this method are appended. This can be used to combine calculations with multiple start points if the mapping fails at a certain condition.

  • 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 new MaterialToMaterialPhaseDiagramResult object which later can be used to get specific values from the calculated result.

disable_global_minimization()

Disables global minimization.

Default: Enabled

Returns

This MaterialToMaterialPhaseDiagramCalculation object

dont_keep_default_equilibria()

Do not keep the initial equilibria added by default.

This is only relevant in combination with add_initial_equilibrium().

This is the default behavior.

Returns

This MaterialToMaterialPhaseDiagramCalculation object

enable_global_minimization()

Enables global minimization.

Default: Enabled

Returns

This MaterialToMaterialPhaseDiagramCalculation object

get_components() List[str]

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

Returns

The component names

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

keep_default_equilibria()

Keep the initial equilibria added by default. This is only relevant in combination with add_initial_equilibrium().

Default behavior is to not keep default equilibria.

Returns

This MaterialToMaterialPhaseDiagramCalculation object

remove_all_initial_equilibria()

Removes all previously added initial equilibria.

Returns

This MaterialToMaterialPhaseDiagramCalculation 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 MaterialToMaterialPhaseDiagramCalculation 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_activities(activities: Dict[str, float])

Sets the constant activity conditions.

Note

The activity conditions are identical for both materials.

Parameters

activities – The constant activities

Returns

This MaterialToMaterialPhaseDiagramCalculation object

set_composition_unit(unit: CompositionUnit = CompositionUnit.MASS_PERCENT)

Sets the composition unit of both materials A and B.

Default: Weight percent

Parameters

unit – The composition unit of both materials A and B

Returns

This MaterialToMaterialPhaseDiagramCalculation 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 MaterialToMaterialPhaseDiagramCalculation object

set_material_a(composition: Dict[str, float], dependent_component: Optional[str] = None)

Sets the composition of the material A.

The unit is set with set_composition_unit().

Tip

The material can also have constant activity conditions, they are set in set_activities().

Parameters
  • composition – The composition of the material A

  • dependent_component – The dependent component of the material A

Returns

This MaterialToMaterialPhaseDiagramCalculation object

set_material_b(composition: Dict[str, float], dependent_component: Optional[str] = None)

Sets the composition of the material B.

The unit is set with set_composition_unit().

Tip

The material can also have constant activity conditions, they are set in set_activities().

Parameters
  • composition – The composition of the material B

  • dependent_component – The dependent component of the material B

Returns

This MaterialToMaterialPhaseDiagramCalculation 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 MaterialToMaterialPhaseDiagramCalculation 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 MaterialToMaterialPhaseDiagramCalculation 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 MaterialToMaterialPhaseDiagramCalculation 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 MaterialToMaterialPhaseDiagramCalculation object

set_pressure(pressure: float)

Sets the pressure (i.e. the condition P).

Note

If the flag default_conditions=True has been set during the creation of the calculator, the pressure is set to 1000 hPa by default.

Parameters

pressure – The pressure [Pa]

Returns

This MaterialToMaterialPhaseDiagramCalculation object

set_system_size(system_size: float)

Sets the system size (i.e. the condition ‘N’, the number of moles).

Note

If the flag default_conditions=True has been set during the creation of the calculator, the system size is set to 1.0 moles by default.

Parameters

system_size – The system size [mole]

Returns

This MaterialToMaterialPhaseDiagramCalculation object

with_first_axis(axis: MaterialToMaterialCalculationAxis)

Sets the first axis (either temperature of fraction of material B). This calculation type requires that both temperature and fraction of material B axis are set.

Parameters

axis – The axis

Returns

This MaterialToMaterialPhaseDiagramCalculation object

with_options(options: PhaseDiagramOptions)

Sets the simulation options.

Parameters

options – The simulation options

Returns

This PhaseDiagramCalculation 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 MaterialToMaterialPhaseDiagramCalculation object

with_second_axis(axis: MaterialToMaterialCalculationAxis)

Sets the second axis (either temperature of fraction of material B). This calculation type requires that both temperature and fraction of material B axis are set.

Parameters

axis – The axis

Returns

This MaterialToMaterialPhaseDiagramCalculation 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 MaterialToMaterialPhaseDiagramCalculation object

class tc_python.material_to_material.MaterialToMaterialPhaseDiagramResult(result)

Bases: PhaseDiagramResult

Result of a Material to Material phase diagram calculation, it can be evaluated using quantities or Console Mode syntax.

add_coordinate_for_phase_label(x: float, y: float)

Sets a coordinate in the result plot for which the stable phases will be evaluated and provided in the result data object. This can be used to plot the phases of a region into the phase diagram or just to programmatically evaluate the phases in certain regions.

Warning

This method takes coordinates of the plot axes and not of the calculation axis.

Parameters
  • x – The coordinate of the first plot axis (“x-axis”) [unit of the plot axis]

  • y – The coordinate of the second plot axis (“y-axis”) [unit of the plot axis]

Returns

This MaterialToMaterialPhaseDiagramResult object

get_values_grouped_by_quantity_of(x_quantity: Union[ThermodynamicQuantity, str], y_quantity: Union[ThermodynamicQuantity, str]) PhaseDiagramResultValues

Returns x-y-line data grouped by the multiple datasets of the specified quantities (for example in dependency of components). The available quantities can be found in the documentation of the factory class ThermodynamicQuantity. Usually the result data represents the phase diagram.

Note

The different datasets will contain NaN-values between different subsections and are not sorted (because they are unsortable due to their nature).

Note

Its possible to use functions as axis variables, either by using ThermodynamicQuantity.user_defined_function, or by using an expression that contains ‘=’.

Example get_values_grouped_by_quantity_of(‘T’, ThermodynamicQuantity.user_defined_function(‘HM.T’))

Example get_values_grouped_by_quantity_of(‘T’, ‘CP=HM.T’)

Parameters
  • x_quantity – The first quantity (“x-axis”), Console Mode syntax strings can be used as an alternative (for example ‘T’), MATERIAL_B_FRACTION, or even a function (for example ‘f=T*1.01’)

  • y_quantity – The second quantity (“y-axis”), Console Mode syntax strings can be used as an alternative (for example ‘NV’), MATERIAL_B_FRACTION, or even a function (for example ‘CP=HM.T’)

Returns

The phase diagram data

get_values_grouped_by_stable_phases_of(x_quantity: Union[ThermodynamicQuantity, str], y_quantity: Union[ThermodynamicQuantity, str]) PhaseDiagramResultValues

Returns x-y-line data grouped by the sets of “stable phases” (for example “LIQUID” or “LIQUID + FCC_A1”). The available quantities can be found in the documentation of the factory class ThermodynamicQuantity. Usually the result data represents the phase diagram.

Note

The different datasets will contain NaN-values between different subsections and are not sorted (because they are unsortable due to their nature).

Note

Its possible to use functions as axis variables, either by using ThermodynamicQuantity.user_defined_function, or by using an expression that contains ‘=’.

Example get_values_grouped_by_quantity_of(‘T’, ThermodynamicQuantity.user_defined_function(‘HM.T’))

Example get_values_grouped_by_quantity_of(‘T’, ‘CP=HM.T’)

Parameters
  • x_quantity – The first quantity (“x-axis”), Console Mode syntax strings can be used as an alternative (for example ‘T’), MATERIAL_B_FRACTION, or even a function (for example ‘f=T*1.01’)

  • y_quantity – The second quantity (“y-axis”), Console Mode syntax strings can be used as an alternative (for example ‘NV’), MATERIAL_B_FRACTION, or even a function (for example ‘CP=HM.T’)

Returns

The phase diagram data

remove_phase_labels()

Erases all added coordinates for phase labels.

Returns

This MaterialToMaterialPhaseDiagramResult object

save_to_disk(path: str)

Saves the result to disc. Note that a 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 MaterialToMaterialPhaseDiagramResult object

set_phase_name_style(phase_name_style_enum: PhaseNameStyle = PhaseNameStyle.NONE)

Sets the style of the phase name labels that will be used in the result data object (constitution description, ordering description, …).

Default: PhaseNameStyle.NONE

Parameters

phase_name_style_enum – The phase name style

Returns

This MaterialToMaterialPhaseDiagramResult object

class tc_python.material_to_material.MaterialToMaterialPropertyDiagramCalculation(calculator)

Bases: AbstractPropertyDiagramCalculation

Configuration for a Material to Material property diagram calculation.

Note

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

calculate(keep_previous_results: bool = False, timeout_in_minutes: float = 0.0) MaterialToMaterialPropertyDiagramResult

Performs the Material to Material property diagram calculation.

Warning

If you use keep_previous_results=True, you must not use another calculator or even get results in between the calculations using calculate(). Then the previous results will actually be lost.

Parameters
  • keep_previous_results – If True, results from any previous call to this method are appended. This can be used to combine calculations with multiple start points if the stepping fails at a certain condition.

  • 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 new MaterialToMaterialPropertyDiagramResult object which later can be used to get specific values from the calculated result

disable_global_minimization()

Disables global minimization.

Default: Enabled

Returns

This MaterialToMaterialPropertyDiagramCalculation object

disable_step_separate_phases()

Disables step separate phases. This is the default setting.

Returns

This MaterialToMaterialPropertyDiagramCalculation object

enable_global_minimization()

Enables global minimization.

Default: Enabled

Returns

This MaterialToMaterialPropertyDiagramCalculation object

enable_step_separate_phases()

Enables step separate phases.

Default: By default separate phase stepping is disabled

Note

This is an advanced option, it is used mostly to calculate how the Gibbs energy for a number of phases varies for different compositions. This is particularly useful to calculate Gibbs energies for complex phases with miscibility gaps and for an ordered phase that is never disordered (e.g. SIGMA-phase, G-phase, MU-phase, etc.).

Returns

This MaterialToMaterialPropertyDiagramCalculation object

get_components() List[str]

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

Returns

The component names

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

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 MaterialToMaterialPropertyDiagramCalculation 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_activities(activities: Dict[str, float])

Sets the constant activity conditions.

Note

The activity conditions are identical for both materials.

Parameters

activities – The constant activities

Returns

This MaterialToMaterialPropertyDiagramCalculation object

set_composition_unit(unit: CompositionUnit = CompositionUnit.MASS_PERCENT)

Sets the composition unit of both materials A and B.

Default: Weight percent

Parameters

unit – The composition unit of both materials A and B

Returns

This MaterialToMaterialPropertyDiagramCalculation 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 MaterialToMaterialPropertyDiagramCalculation object

set_material_a(composition: Dict[str, float], dependent_component: Optional[str] = None)

Sets the composition of the material A.

The unit is set with set_composition_unit().

Tip

The material can also have constant activity conditions, they are set in set_activities().

Parameters
  • composition – The composition of the material A

  • dependent_component – The dependent component of the material A

Returns

This MaterialToMaterialPropertyDiagramCalculation object

set_material_b(composition: Dict[str, float], dependent_component: Optional[str] = None)

Sets the composition of the material B.

The unit is set with set_composition_unit().

Tip

The material can also have constant activity conditions, they are set in set_activities().

Parameters
  • composition – The composition of the material B

  • dependent_component – The dependent component of the material B

Returns

This MaterialToMaterialPropertyDiagramCalculation 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 MaterialToMaterialPropertyDiagramCalculation 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 MaterialToMaterialPropertyDiagramCalculation 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 MaterialToMaterialPropertyDiagramCalculation 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 MaterialToMaterialPropertyDiagramCalculation object

set_pressure(pressure: float)

Sets the pressure (i.e. the condition P).

Note

If the flag default_conditions=True has been set during the creation of the calculator, the pressure is set to 1000 hPa by default.

Parameters

pressure – The pressure [Pa]

Returns

This MaterialToMaterialPropertyDiagramCalculation object

set_system_size(system_size: float)

Sets the system size (i.e. the condition ‘N’, the number of moles).

Note

If the flag default_conditions=True has been set during the creation of the calculator, the system size is set to 1.0 moles by default.

Parameters

system_size – The system size [mole]

Returns

This MaterialToMaterialPropertyDiagramCalculation object

with_axis(axis: MaterialToMaterialCalculationAxis)

Sets the axis (either temperature of fraction of material B). This calculation type requires that either temperature or fraction of material B is set as a constant condition - the other one is set as an axis.

Parameters

axis – The axis

Returns

This MaterialToMaterialPropertyDiagramCalculation object

with_constant_condition(condition: ConstantCondition)

Sets the constant condition (either temperature of fraction of material B). This calculation type requires that either temperature or fraction of material B is set as a constant condition - the other one is set as an axis.

Parameters

condition – The condition

Returns

This MaterialToMaterialPropertyDiagramCalculation object

with_options(options: PropertyDiagramOptions)

Sets the simulation options.

Parameters

options – The simulation options

Returns

This MaterialToMaterialPropertyDiagramCalculation 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 MaterialToMaterialPropertyDiagramCalculation 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 MaterialToMaterialPropertyDiagramCalculation object

class tc_python.material_to_material.MaterialToMaterialPropertyDiagramResult(result)

Bases: PropertyDiagramResult

Result of a Material to Material property diagram. It can be used to query for specific values.

get_values_grouped_by_quantity_of(x_quantity: Union[ThermodynamicQuantity, str], y_quantity: Union[ThermodynamicQuantity, str], sort_and_merge: bool = True) Dict[str, ResultValueGroup]

Returns x-y-line data grouped by the multiple datasets of the specified quantities (typically the phases). The available quantities can be found in the documentation of the factory class ThermodynamicQuantity.

Note

The different datasets might contain NaN-values between different subsections and might not be sorted even if the flag `sort_and_merge` has been set (because they might be unsortable due to their nature).

Note

Its possible to use functions as axis variables, either by using ThermodynamicQuantity.user_defined_function, or by using an expression that contains ‘=’.

Example get_values_grouped_by_quantity_of(‘T’, ThermodynamicQuantity.user_defined_function(‘HM.T’))

Example get_values_grouped_by_quantity_of(‘T’, ‘CP=HM.T’)

Parameters
  • x_quantity – The first quantity (“x-axis”), Console Mode syntax strings can be used as an alternative (for example ‘T’), MATERIAL_B_FRACTION, or even a function (for example ‘f=T*1.01’)

  • y_quantity – The second quantity (“y-axis”), Console Mode syntax strings can be used as an alternative (for example ‘NV’), MATERIAL_B_FRACTION, or even a function (for example ‘CP=HM.T’)

  • sort_and_merge – If True, the data is sorted and merged into as few subsections as possible (divided by NaN)

Returns

Containing the datasets with the quantities as their keys

get_values_grouped_by_stable_phases_of(x_quantity: Union[ThermodynamicQuantity, str], y_quantity: Union[ThermodynamicQuantity, str], sort_and_merge: bool = True) Dict[str, ResultValueGroup]

Returns x-y-line data grouped by the sets of “stable phases” (for example “LIQUID” or “LIQUID + FCC_A1”). The available quantities can be found in the documentation of the factory class ThermodynamicQuantity.

Note

The different datasets might contain NaN-values between different subsections and different lines of an ambiguous dataset. They might not be sorted even if the flag `sort_and_merge` has been set (because they might be unsortable due to their nature).

Note

Its possible to use functions as axis variables, either by using ThermodynamicQuantity.user_defined_function, or by using an expression that contains ‘=’.

Example get_values_grouped_by_quantity_of(‘T’, ThermodynamicQuantity.user_defined_function(‘HM.T’))

Example get_values_grouped_by_quantity_of(‘T’, ‘CP=HM.T’)

Parameters
  • x_quantity – The first quantity (“x-axis”), Console Mode syntax strings can be used as an alternative (for example ‘T’), MATERIAL_B_FRACTION, or even a function (for example ‘f=T*1.01’)

  • y_quantity – The second quantity (“y-axis”), Console Mode syntax strings can be used as an alternative (for example ‘NV’), MATERIAL_B_FRACTION, or even a function (for example ‘CP=HM.T’)

  • sort_and_merge – If True, the data will be sorted and merged into as few subsections as possible (divided by NaN)

Returns

Containing the datasets with the quantities as their keys

get_values_of(x_quantity: Union[ThermodynamicQuantity, str], y_quantity: Union[ThermodynamicQuantity, str]) [List[float], List[float]]

Returns sorted x-y-line data without any separation. Use get_values_grouped_by_quantity_of() or get_values_grouped_by_stable_phases_of() instead if you need such a separation. The available quantities can be found in the documentation of the factory class ThermodynamicQuantity.

Note

This method will always return sorted data without any NaN-values. If it is unsortable that might give data that is hard to interpret. In such a case you need to choose the quantity in another way or use one of the other methods. One example of this is to use quantities with All-markers, for example MassFractionOfAComponent(“All”).

Note

Its possible to use functions as axis variables, either by using ThermodynamicQuantity.user_defined_function(), or by using an expression that contains ‘=’.

Example get_values_grouped_by_quantity_of(‘T’, ThermodynamicQuantity.user_defined_function(‘HM.T’))

Example get_values_grouped_by_quantity_of(‘T’, ‘CP=HM.T’)

Parameters
  • x_quantity – The first thermodynamic quantity (“x-axis”), Console Mode syntax strings can be used as an alternative (for example ‘T’, MATERIAL_B_FRACTION, or even a function (for example ‘f=T*1.01’).

  • y_quantity – The second thermodynamic quantity (“y-axis”), Console Mode syntax strings can be used as an alternative (for example ‘NV’), MATERIAL_B_FRACTION, or even a function (for example ‘CP=HM.T’)

Returns

A tuple containing the x- and y-data in lists

save_to_disk(path: str)

Saves the result to disc. Note that a 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 MaterialToMaterialPropertyDiagramResult object

set_phase_name_style(phase_name_style_enum: PhaseNameStyle = PhaseNameStyle.NONE)

Sets the style of the phase name labels that will be used in the result data object (constitution description, ordering description, …).

Default: PhaseNameStyle.NONE

Parameters

phase_name_style_enum – The phase name style

Returns

This MaterialToMaterialPropertyDiagramResult object

class tc_python.material_to_material.MaterialToMaterialSingleEquilibriumCalculation(calculator)

Bases: AbstractSingleEquilibriumCalculation

Configuration for a Material to Material single fraction of B calculation.

Note

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

calculate(timeout_in_minutes: float = 0.0) MaterialToMaterialSingleEquilibriumResult

Performs the material to material calculation.

Note

The calculation result is no temporary result object.

Parameters

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 new MaterialToMaterialSingleEquilibriumResult 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.

disable_global_minimization()

Turns the global minimization completely off.

Returns

This MaterialToMaterialSingleEquilibriumCalculation object

enable_global_minimization()

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

Returns

This MaterialToMaterialSingleEquilibriumCalculation 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

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 MaterialToMaterialSingleEquilibriumCalculation 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_activities(activities: Dict[str, float])

Sets the constant activity conditions.

Note

The activity conditions are identical for both materials.

Parameters

activities – The constant activities

Returns

This MaterialToMaterialSingleEquilibriumCalculation object

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

set_composition_unit(unit: CompositionUnit = CompositionUnit.MASS_PERCENT)

Sets the composition unit of both materials A and B.

Default: Weight percent

Parameters

unit – The composition unit of both materials A and B

Returns

This MaterialToMaterialSingleEquilibriumCalculation 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 MaterialToMaterialSingleEquilibriumCalculation object

set_material_a(composition: Dict[str, float], dependent_component: Optional[str] = None)

Sets the composition of the material A.

The unit is set with set_composition_unit().

Tip

The material can also have constant activity conditions, they are set in set_activities().

Parameters
  • composition – The composition of the material A

  • dependent_component – The dependent component of the material A

Returns

This MaterialToMaterialSingleEquilibriumCalculation object

set_material_b(composition: Dict[str, float], dependent_component: Optional[str] = None)

Sets the composition of the material B.

The unit is set with set_composition_unit().

Tip

The material can also have constant activity conditions, they are set in set_activities().

Parameters
  • composition – The composition of the material B

  • dependent_component – The dependent component of the material B

Returns

This MaterialToMaterialSingleEquilibriumCalculation 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 MaterialToMaterialSingleEquilibriumCalculation 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 MaterialToMaterialSingleEquilibriumCalculation 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 MaterialToMaterialSingleEquilibriumCalculation 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 MaterialToMaterialSingleEquilibriumCalculation object

set_pressure(pressure: float)

Sets the pressure (i.e. the condition P).

Note

If the flag default_conditions=True has been set during the creation of the calculator, the pressure is set to 1000 hPa by default.

Parameters

pressure – The pressure [Pa]

Returns

This MaterialToMaterialSingleEquilibriumCalculation object

set_system_size(system_size: float)

Sets the system size (i.e. the condition ‘N’, the number of moles).

Note

If the flag default_conditions=True has been set during the creation of the calculator, the system size is set to 1.0 moles by default.

Parameters

system_size – The system size [mole]

Returns

This MaterialToMaterialSingleEquilibriumCalculation object

with_first_constant_condition(condition: ConstantCondition)

Sets the first constant condition (either temperature of fraction of material B).

Parameters

condition – The condition

Returns

This MaterialToMaterialSingleEquilibriumCalculation object

with_options(options: 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 MaterialToMaterialSingleEquilibriumCalculation object

with_second_constant_condition(condition: ConstantCondition)

Sets the second constant condition (either temperature of fraction of material B).

Parameters

condition – The condition

Returns

This MaterialToMaterialSingleEquilibriumCalculation 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 MaterialToMaterialSingleEquilibriumCalculation object

class tc_python.material_to_material.MaterialToMaterialSingleEquilibriumResult(result)

Bases: SingleEquilibriumResult

Result of a Material To Material calculation for a single fraction of material B, 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 MaterialToMaterialSingleEquilibriumResult 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 MaterialToMaterialSingleEquilibriumResult 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[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 MaterialToMaterialSingleEquilibriumResult 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 MaterialToMaterialSingleEquilibriumResult object

class tc_python.material_to_material.TemperatureAxis(from_temperature: float = 1000, to_temperature: float = 3000, start_temperature: float = 2000)

Bases: MaterialToMaterialCalculationAxis

A temperature calculation axis.

class tc_python.material_to_material.TemperatureCondition(temperature: float = 1000.0)

Bases: ConstantCondition

A constant temperature condition.