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.