Package “system”¶

class +tc_toolbox.+system.CompositionSet(phase_name)¶

Used by the method +tc_toolbox.system.SystemBuilder.with_new_composition_set() to enter two or more composition sets for a phase.

Parameters: phase_name – The name of the phase for which a new composition set is required

CompositionSet(phase_name)¶

set_major_constituents_for_sublattice(sublattice_index, major_constituents)¶

Specify the new major constituent(s) for the sublattice.

Default: If not specified, a default is automatically chosen based on the specified composition set.

Note

This is useful in order to make calculations converge faster and more easily (because it may simplify giving start values when calculating the equilibrium as those phases with miscibility gaps should have different major constituents for each composition set). The databases often set major constituents for several phases automatically when the data is retrieved.

Parameters

sublattice_index – Index of the sublattice to set the major constituents for (starting with 1)
major_constituents – Optional list of the major constituents, which must be selected from the phase constitution of the current system.

Returns

This CompositionSet object

class +tc_toolbox.+system.Element(back)¶

Represents an element, making detailed information about the element accessible.

Element(back)¶: Constructs an instance of Element.

get_enthalpy()¶

Returns the enthalpy of the element at 298 K, part of the stable element reference state (SER).

Returns: The enthalpy [J]

get_entropy_diff_0_to_298k()¶

Returns the entropy difference 0 - 298 K of the element, part of the stable element reference state (SER).

Returns: The entropy difference 0 - 298 K [J/K]

get_molar_mass()¶

Returns the molar mass of the element.

Returns: The molar mass [g/mol]

get_name()¶

Returns the name of the element.

Returns: The element name

get_stable_element_reference()¶

Returns the stable element reference (i.e. the stable phase at 298.15 K and 1 bar, reference for all element thermodynamic data).

Returns: The name of the stable element reference

is_interstitial()¶

Returns if the element is interstitial.

Note

In the diffusion simulations (DICTRA), the assumption that the volume is carried by the substitutional elements only is applied. The interstitial elements are assumed to have zero molar volumes.

Returns: If the element is interstitial

is_special()¶

Returns if the element is special (i.e. vacancies (VA) and electrons (denoted either as /- in gaseous, liquid or solid phases, or ZE in an aqueous solution phase)).

Returns: If the element is special

is_valid()¶

Returns if the element is valid. Non-valid elements are represented by an empty name.

Returns: If the element is valid

class +tc_toolbox.+system.MultiDatabaseSystemBuilder(back)¶

Used to select databases, elements, phases etc. and create a System object. The difference to the class SystemBuilder is that the operations are performed on all the previously selected databases. The system is then used to create calculations.

MultiDatabaseSystemBuilder(back)¶: Constructs an instance of MultiDatabaseSystemBuilder.

create_and_select_species(stoichiometry)¶

Specify a species from the already entered elements. The stoichiometry of the species is the chemical formula of the species. The created species will also be automatically selected.

Note

The elements in the chemical formula are normally separated by stoichiometric numbers. Neither parenthesis “()” nor an underscore “_” is allowed in the chemical formula, while the special combination “/-“ or “/+” can be used. Consult the Thermo-Calc database documentation for details about the syntax.

Parameters: stoichiometry – The stoichiometry of the species
Returns: This MultiDatabaseSystemBuilder object

deselect_constituent_on_sublattice(phase_name, sublattice_no, constituent_name_to_deselect)¶

Rejects a constituent on a sublattice in a phase in both the thermodynamic and the kinetic database.

Parameters

phase_name – The name of the phase
sublattice_no – The number of the sublattice (starting with 1)
constituent_name_to_deselect – The name of the constituent to deselect

Returns

This MultiDatabaseSystemBuilder object

deselect_phase(phase_name_to_deselect)¶

Rejects a phase for both the thermodynamic and the kinetic database.

Parameters: phase_name_to_deselect – The phase name
Returns: This MultiDatabaseSystemBuilder object

deselect_species(species_name)¶

Removes the species from the system.

Parameters: species_name – The species
Returns: This MultiDatabaseSystemBuilder object

get_system()¶

Creates a new System object that is the basis for all calculation types. Several calculation types can be defined later from the object; these are independent.

Returns: A new System object

select_constituent_on_sublattice(phase_name, sublattice_no, constituent_name_to_select)¶

Selects a constituent on a sublattice in a phase in both the thermodynamic and the kinetic database.

Note

Previously the third parameter constituent_name_to_select had a wrong name, it has been corrected in version 2021b.

Parameters

phase_name – The name of the phase
sublattice_no – The number of the sublattice (starting with 1)
constituent_name_to_select – The name of the constituent to select

Returns

This MultiDatabaseSystemBuilder object

select_phase(phase_name_to_select)¶

Selects a phase for both the thermodynamic and the kinetic database.

Parameters: phase_name_to_select – The phase name
Returns: This MultiDatabaseSystemBuilder object

select_species(species_name)¶

Adds the species to the system. Up to 1000 species can be defined in a single system.

Parameters: species_name – The species
Returns: This MultiDatabaseSystemBuilder object

with_new_composition_set(composition_set)¶

Used to enter two or more composition sets for a phase. If a phase has a miscibility gap it is necessary to have two composition sets, one for each possible composition that can be stable simultaneously.

The databases often create the typical composition sets for phases automatically when data are retrieved. The equilibrium calculations (using the default settings with global minimization) will usually add new composition sets if needed.

Note

Precipitation and diffusion calculations can require the user to define additional composition sets. E.g. in the case where the new composition set is needed in the configuration of the calculation.

Parameters: composition_set – the composition set
Returns: This MultiDatabaseSystemBuilder object

without_default_phases()¶

Rejects all the default phases from both the thermodynamic and the kinetic database, any phase now needs to be selected manually for the databases.

Returns: This MultiDatabaseSystemBuilder object

class +tc_toolbox.+system.Phase(back)¶

Represents a phase, making detailed information about the phase accessible.

Phase(back)¶: Constructs an instance of Phase.

get_name()¶

Returns the name of the phase.

Returns: The phase name

get_species()¶

Returns the species of the phase.

Returns: A set containing the species

get_species_for_composition_profile()¶

Returns all species that need to be defined in a composition profile of the phase for diffusion simulations - except for one species that needs to be the dependent species.

Note

In a composition profile of a phase for diffusion simulations it is necessary to specify all non-stoichiometric and non-special species. In case of a DILUTE diffusion model, the database enforces the choice of a certain dependent species.

Returns: Set with the species

get_sublattices()¶

Returns the sublattices of the phase in a well-defined contiguous order.

Returns: A list containing the Sublattice objects

get_type()¶

Returns the type of the phase (liquid, ionic liquid, solid, gas).

Returns: The type of a phase

has_diffusion_data()¶

Returns if diffusion data exists for the phase.

Returns: If diffusion data exists for the phase

has_molar_volume_data()¶

Returns if molar volume data exists for the phase.

Returns: If molar volume data exists for the phase

is_dilute_diffusion_model()¶

Returns if diffusion is described using the DILUTE model for the phase. This will always return False if no diffusion data is available.

Returns: If the DILUTE model is used

is_gas()¶

Returns if the phase is a gas phase.

Returns: If the phase is a gas phase

is_ionic_liquid()¶

Returns if the phase is an ionic liquid phase.

Returns: If the phase is an ionic liquid phase

is_liquid()¶

Returns if the phase is a liquid or ionic liquid phase.

Returns: If the phase is a liquid phase

is_solid()¶

Returns if the phase is a solid phase.

Returns: If the phase is a solid phase

class +tc_toolbox.+system.PhaseType¶: The type of a phase.

class +tc_toolbox.+system.Species(back)¶

Represents a species, making detailed information about the species accessible.

Species(back)¶: Constructs an instance of Species.

get_all_elements()¶

Returns all the elements that the species is composed of.

Returns: List of all elements of the species and their stoichiometry

get_charge()¶

Returns the charge of the species.

Returns: The charge of the species

get_name()¶

Returns the name of the species.

Returns: The species name

is_element()¶

Returns if the species actually represents an element.

Returns: If the species represents an element

is_interstitial()¶

Returns if the species is interstitial.

Note

In the diffusion simulations (DICTRA), the assumption that the volume is carried by the substitutional elements only is applied. The interstitial elements are assumed to have zero molar volumes.

Returns: If the species is interstitial

is_special()¶

Returns if the species is special (i.e. vacancies (VA) and electrons (denoted either as /- in gaseous, liquid or solid phases, or ZE in an aqueous solution phase)).

Returns: If the species is special

is_valid()¶

Returns if the species is valid. Non-valid species are represented by an empty name.

Returns: If the species is valid

to_element()¶

Returns the Element representation of the species - if the species actually represents an element.

Returns: The Element object

class +tc_toolbox.+system.Sublattice(back)¶

Represents a sublattice of a phase.

Sublattice(back)¶: Constructs an instance of Sublattice.

get_constituents()¶

Returns the constituents of the sublattice.

Returns: A set containing the constituents

get_nr_of_sites()¶

Returns the number of sites in the sublattice.

Returns: A float number

class +tc_toolbox.+system.System(back)¶

A system containing selections for databases, elements, phases etc.

Note

For the defined system, different calculations can be configured and run. Instances of this class should always be created from a SystemBuilder.

Note

The system object is immutable, i.e. it cannot be changed after is has been created. If you want to change the system, you must instead create a new one.

System(back)¶: Constructs an instance of System.

convert_composition(input_composition, input_unit, output_unit, dependent_component)¶

Provides conversion between composition units for any combination of chemical compounds. It is fast because no thermodynamic equilibrium calculation is involved.

Syntax of the chemical compounds: “Al2O3”, “FeO”, “CO”, “Fe”, “C”, …

Note

It is not required that the chemical compounds are components of the database. The only requirement is that all elements are present in the database.

Parameters

input_composition – Composition (for example: {“Al2O3”: 25.0, “FeO”: 75.0})
input_unit – Unit of the input composition
output_unit – Requested output unit
dependent_component – The dependent component (optional), for example: “Fe”. If no dependent component is specified the sum of the input composition needs to match 100% / 1

Returns

The composition in the requested output unit

get_all_elements_in_databases()¶

Returns the names of all elements present in the selected databases, regardless of the actual selection of elements.

Returns: A list of element names

get_all_phases_in_databases()¶

Returns all phase names present in the selected databases, regardless of selected elements, phases etc.

Returns: A list of phase names

get_all_species_in_databases()¶

Returns all species names present in the selected databases, regardless of the actual selection of elements, phases, ….

Returns: A list of species names

get_element_object(element_name)¶

Returns the Element object of an element. This can be used to obtain detailed information about the element.

Parameters: element_name – The element name
Returns: object
Return type: A Element

get_elements_in_system()¶

Returns the names of all elements present in the selected system.

Note

The list does not contain any elements or components that have been auto-selected by the database(s) in a calculator. Use the get_components() of the calculator object instead to get the complete information.

Returns: A list of element names

get_phase_object(phase_name)¶

Returns the Phase object of a phase. This can be used to obtain detailed information about the phase.

Parameters: phase_name – The phase name
Returns: object
Return type: A Phase

get_phases_in_system()¶

Returns all phase names present in the system due to its configuration (selected elements, phases, etc.).

Returns: A list of phase names

get_references()¶

Provides a dictionary with database references per database in the selected system.

Returns: The database references

get_species_in_system()¶

Returns the names of all species present in the selected system.

Note

The list does not contain any species or components that have been auto-selected by the database(s) in a calculator. Use the get_components() of the calculator object instead to get the complete information.

Returns: The list of species names

get_species_object(species_name)¶

Returns the Species object of an species. This can be used to obtain detailed information about the species.

Parameters: species_name – The species name
Returns: object
Return type: A Species

get_system_data()¶

Returns the content of the database. 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

with_batch_equilibrium_calculation(default_conditions, components)¶

Creates a batch-equilibrium calculation (a vectorized equilibrium calculation).

Note

Use this instead of looping if you want to calculate equilibria for a larger number of compositions and know the conditions in advance. This calculation type has improved performance when calculating a large number of equilibria when each individual calculations is quick. E.g. when evaluating single phase properties for thousands of compositions.

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

with_cct_precipitation_calculation()¶

Creates a CCT diagram calculation.

Returns: A new PrecipitationCCTCalculation object

with_isothermal_diffusion_calculation()¶

Creates an isothermal diffusion calculation.

Returns: A new DiffusionIsoThermalCalculation object

with_isothermal_precipitation_calculation()¶

Creates an isothermal precipitation calculation.

Returns: A new PrecipitationIsoThermalCalculation object

with_material_to_material()¶

Provides access to all Material to Material calculations. The actual calculation needs to be chosen in the returned object.

Returns: A new MaterialToMaterialCalculationContainer object

with_non_isothermal_diffusion_calculation()¶

Creates a non-isothermal precipitation calculation.

Returns: A new PrecipitationNonIsoThermalCalculation object

with_non_isothermal_precipitation_calculation()¶

Creates a non-isothermal precipitation calculation.

Returns: A new PrecipitationNonIsoThermalCalculation object

with_phase_diagram_calculation(default_conditions, components)¶

Creates a 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 PhaseDiagramCalculation object

with_property_diagram_calculation(default_conditions, components)¶

Creates a 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 PropertyDiagramCalculation object

with_property_model_calculation(model, path_to_models, debug_model)¶

Creates a Property Model calculation.

The parameter debug_model is only used when debugging self-developed models.

Parameters

model – The Property Model to be calculated.
path_to_models – The path where the Property Models are installed. If no value is entered, the Property Models folder used by the normal Thermo-Calc application is used.
debug_model – Used when debugging self-developed models.

Returns

A new PropertyModelCalculation object

with_scheil_calculation()¶

Creates a Scheil solidification calculation.

Warning

Scheil calculations do not support the GAS phase being selected, this means the `GAS` phase must always be deselected in the system if it is present in the database

Returns: A new ScheilCalculation object

with_single_equilibrium_calculation(default_conditions, components)¶

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

with_ttt_precipitation_calculation()¶

Creates a TTT diagram calculation.

Returns: A new PrecipitationTTTCalculation object

class +tc_toolbox.+system.SystemBuilder(back)¶

Used to select databases, elements, phases etc. and create a System object. The system is then used to create calculations.

SystemBuilder(back)¶: Constructs an instance of SystemBuilder.

create_and_select_species(stoichiometry)¶

Specify a species from the already entered elements. The stoichiometry of the species is the chemical formula of the species. The created species will also be automatically selected.

Note

The elements in the chemical formula are normally separated by stoichiometric numbers. Neither parenthesis “()” nor an underscore “_” is allowed in the chemical formula, while the special combination “/-“ or “/+” can be used. Consult the Thermo-Calc database documentation for details about the syntax.

Parameters: stoichiometry – The stoichiometry of the species
Returns: This SystemBuilder object

deselect_constituent_on_sublattice(phase_name, sublattice_no, constituent_name_to_deselect)¶

Rejects a constituent on a sublattice in a phase in the last specified database only.

Parameters

phase_name – The name of the phase
sublattice_no – The number of the sublattice (starting with 1)
constituent_name_to_deselect – The name of the constituent to deselect

Returns

This SystemBuilder object

deselect_phase(phase_name_to_deselect)¶

Rejects a phase in the last specified database only.

Parameters: phase_name_to_deselect – The name of the phase
Returns: This SystemBuilder object

deselect_species(stoichiometry)¶

Removes the species from the system.

Parameters: stoichiometry – The species
Returns: This SystemBuilder object

get_system()¶

Creates a new System object that is the basis for all calculation types. Several calculation types can be defined later from the object; these are independent.

Returns: A new System object

get_system_for_scheil_calculations()¶

Creates a new System object without gas phases being selected, that is the basis for all calculation types, but its particularly useful for Scheil solidification calculations, where the model does not allow that a gas phase is selected in the system.

Several calculation types can be defined later from the object; these are independent.

Note

Deprecated in version 2022b: Use get_system() instead. There are no longer any special requirements from the Thermo-Calc program to deselect the gas phase for Scheil. It will be removed in release 2023b.

Returns: A new System object

select_constituent_on_sublattice(phase_name, sublattice_no, constituent_name_to_select)¶

Selects a constituent on a sublattice in a phase in the last specified database only.

Note

Previously the third parameter constituent_name_to_select had a wrong name, it has been corrected in version 2021b.

Parameters

phase_name – The name of the phase
sublattice_no – The number of the sublattice (starting with 1)
constituent_name_to_select – The name of the constituent to select

Returns

This SystemBuilder object

select_database_and_elements(database_name, list_of_element_strings)¶

Selects a thermodynamic or kinetic database and its selected elements (that will be appended). After that, phases can be selected or unselected.

Parameters

database_name – The database name, for example “FEDEMO”
list_of_element_strings – A list of one or more elements as strings, for example [“Fe”, “C”]

Returns

This SystemBuilder object

select_phase(phase_name_to_select)¶

Selects a phase in the last specified database only.

Parameters: phase_name_to_select – The name of the phase
Returns: This SystemBuilder object

select_species(stoichiometry)¶

Adds the species to the system. Up to 1000 species can be defined in a single system.

Parameters: stoichiometry – The species
Returns: This SystemBuilder object

select_user_database_and_elements(path_to_user_database, list_of_element_strings)¶

Selects a thermodynamic database which is a user-defined database and select its elements (that will be appended).

Note

By using a r-literal, it is possible to use slashes on all platforms, also on Windows: select_user_database_and_elements(r”my path/user_db.tdb”, [“Fe”, “Cr”]])

Note

On Linux and Mac the path is case-sensitive, also the file ending.

Parameters

path_to_user_database – The path to the database file (“database”.TDB), defaults to the current working directory. Only the filename is required if the database is located in the same folder as the script.
list_of_element_strings – A list of one or more elements as strings, for example [“Fe”, “C”]

Returns

This SystemBuilder object

with_new_composition_set(composition_set)¶

Used to enter composition sets for a phase. If a phase has a miscibility gap it is necessary to have two composition sets, one for each possible composition that can be stable simultaneously.

Parameters: composition_set – The composition set
Returns: This SystemBuilder object

without_default_phases()¶

Rejects all default phases in the last specified database only, any phase needs now to be selected manually for that database.

Returns: This SystemBuilder object