Module “diffusion”

class tc_python.diffusion.AbstractBoundaryCondition

Bases: object

The abstract base class for all boundary conditions.

class tc_python.diffusion.AbstractCalculatedGrid

Bases: AbstractGrid

The abstract base class for calculated grids.

class tc_python.diffusion.AbstractElementProfile

Bases: object

The abstract base class for all initial composition profile types.

class tc_python.diffusion.AbstractGrid

Bases: object

The abstract base class for all grids.

class tc_python.diffusion.AbstractSolver

Bases: object

Abstract base class for the solvers (Classic, Homogenization and Automatic).

class tc_python.diffusion.ActivityFluxFunction

Bases: BoundaryCondition

get_type() str

The type of the boundary condition.

Returns:

The type

set_flux_function(element_name: str, f: str = '0', g: str = '1', n: float = 1.0, to_time: float = 1.7976931348623157e+308)

The flux for the independent components must be given in the format:

J = f(T,P,TIME) * ( ACTIVITY^N - g(T,P,TIME) )

where f and g may be functions of time (TIME), temperature (T), and pressure (P), and N is an integer.

f and g must be expressed in DICTRA Console Mode syntax.

Parameters:
  • element_name – The name of the element

  • f – the function f in the formula above

  • g – the function g in the formula above

  • n – the constant N in the formula above

  • to_time – The max-time for which the flux function is used.

class tc_python.diffusion.AutomaticSolver

Bases: Solver

Solver using the homogenization model if any region has more than one phase, otherwise using the classic model.

Note

This is the default solver and recommended for most applications.

get_type() str

The type of the solver.

Returns:

The type

set_flux_balance_equation_accuracy(accuracy: float = 1e-16)

Only valid if the :class:`ClassicSolver` is actually used (i.e. not more than one phase in each region).

Sets the required accuracy during the solution of the flux balance equations. Default: 1.0e-16

Parameters:

accuracy – The required accuracy

Returns:

A new AutomaticSolver object

set_tieline_search_variable_to_activity()

Only valid if the :class:`ClassicSolver` is actually used (i.e. not more than one phase in each region).

Configures the solver to use the activity of a component to find the correct tie-line at the phase interface. Either activity or chemical potential are applied to reduce the degrees of freedom at the local equilibrium. Default: This is the default setting

Returns:

A new AutomaticSolver object

set_tieline_search_variable_to_potential()

Only valid if the :class:`ClassicSolver` is actually used (i.e. not more than one phase in each region).

Configures the solver to use the chemical potential of a component to find the correct tie-line at the phase interface. Either activity or chemical potential are applied to reduce the degrees of freedom at the local equilibrium. Default: To use the activity

Returns:

A new AutomaticSolver object

class tc_python.diffusion.BoundaryCondition

Bases: AbstractBoundaryCondition

Contains factory methods for the the different boundary conditions available.

classmethod activity_flux_function()

Factory method that creates a new activity-flux-function boundary condition.

This type of boundary condition is used to take into account the finite rate of a surface reaction.

The flux for the independent components must be given in the format:

J = f(T,P,TIME) * ( ACTIVITY^N - g(T,P,TIME) )

where f and g may be functions of time (TIME), temperature (T), and pressure (P), and N is an integer.

f and g must be expressed in DICTRA Console Mode syntax.

Note

The activities are those with user-defined reference states. The function mass transfer coefficient is the mass transfer coefficient, activity of the corresponding species in the gas is the activity of the corresponding species in the gas and N is a stoichiometric coefficient.

Note

For more details see L. Sproge and J. Ågren, “Experimental and theoretical studies of gas consumption in the gas carburizing process” J. Heat Treat. 6, 9–19 (1988).

Returns:

A new ActivityFluxFunction object

classmethod closed_system()

Factory method that creates a new closed-system boundary condition.

Returns:

A new ClosedSystem object

classmethod fix_flux_value()

Factory method that creates a new fix-flux-value boundary condition.

This type of boundary condition makes it possible to enter functions that yield the flux times the molar volume for the independent components. May be a function of time, temperature and pressure: J(T,P,TIME).

Returns:

A new FixFluxValue object

classmethod fixed_compositions(unit_enum: Unit = Unit.MASS_PERCENT)

Factory method that creates a new fixed-composition boundary condition.

Parameters:

unit_enum – The composition unit

Returns:

A new FixedCompositions object

classmethod mixed_zero_flux_and_activity()

Factory method that creates a new mixed zero-flux and activity boundary condition

Returns:

A new MixedZeroFluxAndActivity object

class tc_python.diffusion.CalculatedGrid

Bases: AbstractCalculatedGrid

Factory class for grids generated by a mathematical series (linear, geometric, …). Use tc_python.diffusion.PointByPointGrid instead if you want to use an existing grid from experimental data or a previous calculation.

Note

A region must contain a number of grid points. The composition is only known at these grid points and the software assumes that the composition varies linearly between them. The amount and composition of all the phases present at a single grid point in a certain region are those given by thermodynamic equilibrium keeping the over-all composition at the grid point fixed.

classmethod double_geometric(no_of_points: int = 50, lower_geometrical_factor: float = 1.1, upper_geometrical_factor: float = 0.9)

Factory method that creates a new double geometric grid.

Note

Double geometric grids have a high number of grid points in the middle or at both ends of a region. One geometrical factor for the lower (left) and upper (right) half of the region need to specified. In both cases a geometrical factor of larger than one yields a higher density of grid points at the lower end of the half and vice versa for a factor smaller than one.

Parameters:
  • no_of_points – The number of points

  • lower_geometrical_factor – The geometrical factor for the left half

  • upper_geometrical_factor – The geometrical factor for the right half

Returns:

A new DoubleGeometricGrid object

classmethod geometric(no_of_points: int = 50, geometrical_factor: float = 1.1)

Factory method that creates a new geometric grid.

Note

A grid that yields a varying density of grid points in the region. A geometrical factor larger than one yields a higher density of grid points at the lower end of the region and a factor smaller than one yields a higher density of grid points at the upper end of the region.

Parameters:
  • no_of_points – The number of points

  • geometrical_factor – The geometrical factor

Returns:

A new GeometricGrid object

classmethod linear(no_of_points: int = 50)

Factory method that creates a new equally spaced grid.

Parameters:

no_of_points – The number of points

Returns:

A new LinearGrid object

class tc_python.diffusion.ClassicSolver

Bases: Solver

Solver using the Classic model.

Note

This solver never switches to the homogenization model even if it fails to converge. Use the tc_python.diffusion.AutomaticSolver if necessary instead.

get_type() str

Convenience method for getting the type of the solver.

Returns:

The type of the solver

set_flux_balance_equation_accuracy(accuracy: float = 1e-16)

Sets the required accuracy during the solution of the flux balance equations. Default: 1.0e-16

Parameters:

accuracy – The required accuracy

Returns:

A new ClassicSolver object

set_tieline_search_variable_to_activity()

Configures the solver to use the activity of a component to find the correct tie-line at the phase interface. Either activity or chemical potential are applied to reduce the degrees of freedom at the local equilibrium. Default: This is the default setting

set_tieline_search_variable_to_potential()

Configures the solver to use the chemical potential of a component to find the correct tie-line at the phase interface. Either activity or chemical potential are applied to reduce the degrees of freedom at the local equilibrium. Default: To use the activity

Returns:

A new ClassicSolver object

class tc_python.diffusion.ClosedSystem

Bases: BoundaryCondition

Represents a boundary for a closed system.

get_type() str

Convenience method for getting the type of the boundary condition.

Returns:

The type of the boundary condition

class tc_python.diffusion.CompositionProfile(unit_enum: Unit = Unit.MASS_PERCENT)

Bases: object

Contains initial concentration profiles for the elements.

add(element_name: str, profile: ElementProfile)

Adds a concentration profile for the specified element.

Parameters:
  • element_name – The name of the element

  • profile – The initial concentration profile

Returns:

A CompositionProfile object

class tc_python.diffusion.ConstantProfile(value: float)

Bases: ElementProfile

Represents a constant initial concentration profile.

get_type() str

The type of the element profile.

Returns:

The type

class tc_python.diffusion.ContinuedDiffusionCalculation(calculation)

Bases: AbstractCalculation

Configuration for a diffusion calculation that is a continuation of a previous isothermal or non-isothermal diffusion calculation. It contains a subset of the settings possible in the original calculation.

Use set_simulation_time() to set a simulation time that is higher than the original calculation.

calculate(timeout_in_minutes: float = 0.0) DiffusionCalculationResult

Runs the diffusion calculation.

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

set_simulation_time(simulation_time: float)

Sets the simulation time.

Parameters:

simulation_time – The simulation time [s]

Returns:

This DiffusionIsoThermalCalculation object

with_left_boundary_condition(boundary_condition: BoundaryCondition, to: float = 1.7976931348623157e+308)

Defines the boundary condition on the left edge of the system.

Default: A closed-system boundary condition.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Note

You can specify time-dependent boundary conditions by calling with_left_boundary_condition() many times, with different values of the “to” parameter.

Examples:

  • with_left_boundary_condition(BoundaryCondition.closed_system(), to=100)

  • with_left_boundary_condition(BoundaryCondition.mixed_zero_flux_and_activity().set_activity_for_element(“C”, surface_activity), to=500)

  • with_left_boundary_condition(BoundaryCondition.closed_system())

This example sets an closed-system-boundary-condition from start up to 100s and a activity-boundary-condition from 100s to 500s and finally a closed-system-boundary-condition from 500s to the end of simulation.

Parameters:
  • boundary_condition – The boundary condition

  • to – The upper time-limit for boundary_condition.

Returns:

This DiffusionIsoThermalCalculation object

with_options(options: Options, to: float = 1.7976931348623157e+308)

Sets the general simulation conditions.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Parameters:
  • options – The general simulation conditions

  • to – The upper time-limit for options.

Returns:

This DiffusionIsoThermalCalculation object

with_right_boundary_condition(boundary_condition: BoundaryCondition, to: float = 1.7976931348623157e+308)

Defines the boundary condition on the right edge of the system.

Default: A closed-system boundary condition

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Note

You can specify time-dependent boundary conditions by calling with_right_boundary_condition() many times, with different values of the “to” parameter.

Examples:

  • with_right_boundary_condition(BoundaryCondition.closed_system(), to=100)

  • with_right_boundary_condition(BoundaryCondition.mixed_zero_flux_and_activity().set_activity_for_element(“C”, surface_activity), to=500)

  • with_right_boundary_condition(BoundaryCondition.closed_system())

This example sets an closed-system-boundary-condition from start up to 100s and a activity-boundary-condition from 100s to 500s and finally a closed-system-boundary-condition from 500s to the end of simulation.

Parameters:
  • boundary_condition – The boundary condition

  • to – The upper time-limit for boundary_condition.

Returns:

This DiffusionIsoThermalCalculation object

with_solver(solver: Solver, to: float = 1.7976931348623157e+308)

Sets the solver to use (Classic, Homogenization or Automatic). Default is Automatic.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Parameters:
  • solver – The solver to use

  • to – The upper time-limit for solver.

Returns:

This DiffusionIsoThermalCalculation object

with_timestep_control(timestep_control: TimestepControl, to: float = 1.7976931348623157e+308)

Sets the timestep control options.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Parameters:
  • timestep_control – The new timestep control options

  • to – The upper time-limit for timestep_control.

Returns:

This DiffusionIsoThermalCalculation object

class tc_python.diffusion.DiffusionCalculationResult(result)

Bases: AbstractResult

Result of a diffusion calculation. This can be used to query for specific values. For details of the axis variables, search the Thermo-Calc help.

get_mass_fraction_at_lower_interface(region: str, component: str) [List[float], List[float]]

Returns the mass fraction of the specified component at the lower boundary of the specified region, in dependency of time.

Parameters:
  • region – The name of the region

  • component – The name of the component

Returns:

A tuple of two lists of floats (time [s], mass fraction of the specified component)

get_mass_fraction_at_upper_interface(region: str, component: str) [List[float], List[float]]

Returns the mass fraction of the specified component at the upper boundary of the specified region, in dependency of time.

Parameters:
  • region – The name of the region

  • component – The name of the component

Returns:

A tuple of two lists of floats (time [s], mass fraction of the specified component)

get_mass_fraction_of_component_at_time(component: str, time: Union[SimulationTime, float]) [List[float], List[float]]

Returns the mass fraction of the specified component at the specified time.

Note

Use the enum tc_python.diffusion.SimulationTime to choose the first or the last timepoint of the simulation. A timepoint close to the last one should never be specified manually because the actual end of the simulation can slightly deviate.

Parameters:
  • component – The name of the component

  • time – The time [s]

Returns:

A tuple of two lists of floats (distance [m], mass fraction of component at the specified time)

get_mass_fraction_of_phase_at_time(phase: str, time: Union[SimulationTime, float]) [List[float], List[float]]

Returns the mass fraction of the specified phase.

Note

Use the enum tc_python.diffusion.SimulationTime to choose the first or the last timepoint of the simulation. A timepoint close to the last one should never be specified manually because the actual end of the simulation can slightly deviate.

Parameters:
  • phase – The name of the phase

  • time – The time [s]

Returns:

A tuple of two lists of floats (distance [m], mass fraction of hte phase at the specified time)

get_mole_fraction_at_lower_interface(region: str, component: str) [List[float], List[float]]

Returns the mole fraction of the specified component at the lower boundary of the specified region, in dependency of time.

Parameters:
  • region – The name of the region

  • component – The name of the component

Returns:

A tuple of two lists of floats (time [s], mole fraction of the specified component)

get_mole_fraction_at_upper_interface(region: str, component: str) [List[float], List[float]]

Returns the mole fraction of the specified component at the upper boundary of the specified region, in dependency of time.

Parameters:
  • region – The name of the region

  • component – The name of the component

Returns:

A tuple of two lists of floats (time [s], mole fraction of the specified component)

get_mole_fraction_of_component_at_time(component: str, time: Union[SimulationTime, float]) [List[float], List[float]]

Returns the mole fraction of the specified component at the specified time.

Note

Use the enum tc_python.diffusion.SimulationTime to choose the first or the last timepoint of the simulation. A timepoint close to the last one should never be specified manually because the actual end of the simulation can slightly deviate.

Parameters:
  • component – The name of the component

  • time – The time [s]

Returns:

A tuple of two lists of floats (distance [m], mole fraction of component at the specified time)

get_mole_fraction_of_phase_at_time(phase: str, time: Union[SimulationTime, float]) [List[float], List[float]]

Returns the mole fraction of the specified phase.

Note

Use the enum tc_python.diffusion.SimulationTime to choose the first or the last timepoint of the simulation. A timepoint close to the last one should never be specified manually because the actual end of the simulation can slightly deviate.

Parameters:
  • phase – The name of the phase

  • time – The time [s]

Returns:

A tuple of two lists of floats (distance [m], mole fraction of the phase at the specified time)

get_position_of_lower_boundary_of_region(region: str) [List[float], List[float]]

Returns the position of the lower boundary of the specified region in dependency of time.

Parameters:

region – The name of the region

Returns:

A tuple of two lists of floats (time [s], position of lower boundary of region [m])

get_position_of_upper_boundary_of_region(region: str) [List[float], List[float]]

Returns the position of the upper boundary of the specified region in dependency of time.

Parameters:

region – The name of the region

Returns:

A tuple of two lists of floats (time [s], position of upper boundary of region [m])

get_regions() List[str]

Returns the regions of the diffusion simulation.

Note

Automatically generated regions (R_###) are included in the list.

Returns:

The region names

get_time_steps() List[float]

Returns the timesteps of the diffusion simulation.

Returns:

The timesteps [s]

get_total_mass_fraction_of_component(component: str) [List[float], List[float]]

Returns the total mass fraction of the specified component in dependency of time.

Parameters:

component – The name of the component

Returns:

A tuple of two lists of floats (time [s], total mass fraction of the component)

get_total_mass_fraction_of_component_in_phase(component: str, phase: str) [List[float], List[float]]

Returns the total mass fraction of the specified component in the specified phase in dependency of time.

Parameters:
  • component – The name of the component

  • phase – The name of the phase

Returns:

A tuple of two lists of floats (time [s], total mass fraction of the component in the phase)

get_total_mass_fraction_of_phase(phase: str) [List[float], List[float]]

Returns the total mass fraction of the specified phase in dependency of the time.

Parameters:

phase – The name of the phase

Returns:

A tuple of two lists of floats (time [s], total mass fraction of the phase)

get_total_mole_fraction_of_component(component: str) [List[float], List[float]]

Returns the total mole fraction of the specified component in dependency of time.

Parameters:

component – The name of the component

Returns:

A tuple of two lists of floats (time [s], total mole fraction of the component)

get_total_mole_fraction_of_component_in_phase(component: str, phase: str) [List[float], List[float]]

Returns the total mole fraction of the specified component in the specified phase in dependency of time.

Parameters:
  • component – The name of the component

  • phase – The name of the phase

Returns:

A tuple of two lists of floats (time [s], total mole fraction of the component in the phase)

get_total_mole_fraction_of_phase(phase: str) [List[float], List[float]]

Returns the total mole fraction of the specified phase in dependency of time.

Parameters:

phase – The name of the phase

Returns:

A tuple of two lists of floats (time [s], total mole fraction of the phase)

get_total_volume_fraction_of_phase(phase: str) [List[float], List[float]]

Returns the total volume fraction of the specified phase in dependency of the time.

Parameters:

phase – The name of the phase

Returns:

A tuple of two lists of floats (time [s], total volume fraction of the phase)

get_values_of(x_axis: Union[DiffusionQuantity, str], y_axis: Union[DiffusionQuantity, str], plot_condition: Union[PlotCondition, str] = '', independent_variable: Union[IndependentVariable, str] = '') [List[float], List[float]]

Returns the specified result from the simulation, allows all possible settings.

Note

As an alternative, DICTRA Console Mode syntax can be used as well for each quantity and condition.

Warning

This is an advanced mode that is equivalent to the possibilities in the DICTRA Console Mode. Not every combination of settings will return a result.

Parameters:
  • x_axis – The first result quantity

  • y_axis – The second result quantity

  • plot_condition – The plot conditions

  • independent_variable – The independent variable

Returns:

A tuple of two lists of floats (the x_axis quantity result, the y_axis quantity result) [units according to the quantities]

get_velocity_of_lower_boundary_of_region(region: str) [List[float], List[float]]

Returns the velocity of the lower boundary of the specified region in dependency of time.

Parameters:

region – The name of the region

Returns:

A tuple of two lists of floats (time [s], velocity of lower boundary of region [m/s])

get_velocity_of_upper_boundary_of_region(region: str) [List[float], List[float]]

Returns the velocity of the upper boundary of the specified region in dependency of time.

Parameters:

region – The name of the region

Returns:

A tuple of two lists of floats (time [s], velocity of upper boundary of region [m/s])

get_width_of_region(region: str) [List[float], List[float]]

Returns the width of region, in dependency of time.

Parameters:

region – The name of the region

Returns:

A tuple of two lists of floats (time [s], width of the specified region [m])

save_to_disk(path: str)

Saves the result to disk. The result can later be loaded using tc_python.server.SetUp.load_result_from_disk().

Note

The result data is represented by a whole folder containing multiple files.

Parameters:

path – The path to the result folder, can be relative or absolute.

Returns:

This DiffusionCalculationResult object

with_continued_calculation()

Returns a ContinuedDiffusionCalculation that is used for continuing a diffusion calculation with altered settings.

Returns:

A ContinuedDiffusionCalculation

class tc_python.diffusion.DiffusionIsoThermalCalculation(calculation)

Bases: AbstractCalculation

Configuration for an isothermal diffusion calculation.

add_console_command(console_command: str)

Registers a DICTRA Console Mode command for execution. These commands are executed after all other configuration directly before the calculation starts to run. All commands are stored and used until explicitly deleted using tc_python.diffusion.DiffusionIsoThermoCalculation.remove_all_console_commands.

Parameters:

console_command – The DICTRA Console Mode command

Returns:

This DiffusionIsoThermalCalculation 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 DICTRA-commands directly in the engine, it may hang the program in case of spelling mistakes (e.g. forgotten parenthesis, …).

add_region(region: Region)

Adds a region to the calculation. Regions are always added in the simulation domain from left to right.

If you want to replace an already added region, call remove_all_regions(), and add the regions that you want to keep.

Warning

Regions must have unique names.

Parameters:

region – The region to be added

Returns:

This DiffusionIsoThermalCalculation object

calculate(timeout_in_minutes: float = 0.0) DiffusionCalculationResult

Runs the diffusion calculation.

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

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

remove_all_console_commands()

Removes all previously added Console Mode commands.

Returns:

This DiffusionIsoThermalCalculation object

remove_all_regions()

Removes all previously added regions.

:return This DiffusionIsoThermalCalculation object

set_simulation_time(simulation_time: float)

Sets the simulation time.

Parameters:

simulation_time – The simulation time [s]

Returns:

This DiffusionIsoThermalCalculation object

set_temperature(temperature: float)

Sets the temperature for the isothermal simulation.

Parameters:

temperature – The temperature [K]

Returns:

This DiffusionIsoThermalCalculation object

with_cylindrical_geometry(first_interface_position: float = 0.0)

Sets geometry to cylindrical, corresponds to an infinitely long cylinder of a certain radius.

Default: A planar geometry

Note

With a cylindrical or spherical geometry, the system’s zero coordinate (left boundary) is at the centre of the cylinder or sphere by default. By specifying the first_interface_position, a different left-most coordinate can be defined. This allows to model a tube or a hollow sphere geometry. The highest coordinate (right boundary) is defined by the cylinder or sphere radius (i.e. by the width of all regions).

Parameters:

first_interface_position – The position of the left-most coordinate along the axis, only necessary for modeling a tube geometry [m]

Returns:

This DiffusionIsoThermalCalculation object

with_left_boundary_condition(boundary_condition: BoundaryCondition, to: float = 1.7976931348623157e+308)

Defines the boundary condition on the left edge of the system.

Default: A closed-system boundary condition.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Note

You can specify time-dependent boundary conditions by calling with_left_boundary_condition() many times, with different values of the “to” parameter.

Examples:

  • with_left_boundary_condition(BoundaryCondition.closed_system(), to=100)

  • with_left_boundary_condition(BoundaryCondition.mixed_zero_flux_and_activity().set_activity_for_element(“C”, surface_activity), to=500)

  • with_left_boundary_condition(BoundaryCondition.closed_system())

This example sets an closed-system-boundary-condition from start up to 100s and a activity-boundary-condition from 100s to 500s and finally a closed-system-boundary-condition from 500s to the end of simulation.

Parameters:
  • boundary_condition – The boundary condition

  • to – The upper time-limit for boundary_condition.

Returns:

This DiffusionIsoThermalCalculation object

with_options(options: Options, to: float = 1.7976931348623157e+308)

Sets the general simulation conditions.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Parameters:
  • options – The general simulation conditions

  • to – The upper time-limit for options.

Returns:

This DiffusionIsoThermalCalculation object

with_planar_geometry()

Sets geometry to planar.

This is default.

Returns:

This DiffusionIsoThermalCalculation object

with_reference_state(element: 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:
  • element – The name of the element

  • 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 DiffusionIsoThermalCalculation object

with_right_boundary_condition(boundary_condition: BoundaryCondition, to: float = 1.7976931348623157e+308)

Defines the boundary condition on the right edge of the system.

Default: A closed-system boundary condition

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Note

You can specify time-dependent boundary conditions by calling with_right_boundary_condition() many times, with different values of the “to” parameter.

Examples:

  • with_right_boundary_condition(BoundaryCondition.closed_system(), to=100)

  • with_right_boundary_condition(BoundaryCondition.mixed_zero_flux_and_activity().set_activity_for_element(“C”, surface_activity), to=500)

  • with_right_boundary_condition(BoundaryCondition.closed_system())

This example sets an closed-system-boundary-condition from start up to 100s and a activity-boundary-condition from 100s to 500s and finally a closed-system-boundary-condition from 500s to the end of simulation.

Parameters:
  • boundary_condition – The boundary condition

  • to – The upper time-limit for boundary_condition.

Returns:

This DiffusionIsoThermalCalculation object

with_solver(solver: Solver, to: float = 1.7976931348623157e+308)

Sets the solver to use (Classic, Homogenization or Automatic). Default is Automatic.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Parameters:
  • solver – The solver to use

  • to – The upper time-limit for solver.

Returns:

This DiffusionIsoThermalCalculation object

with_spherical_geometry(first_interface_position: float = 0.0)

Sets geometry to spherical, corresponds to a sphere with a certain radius.

Default: A spherical geometry

Note

With a cylindrical or spherical geometry, the system’s zero coordinate (left boundary) is at the centre of the cylinder or sphere by default. By specifying the first_interface_position, a different left-most coordinate can be defined. This allows to model a tube or a hollow sphere geometry. The highest coordinate (right boundary) is defined by the cylinder or sphere radius (i.e. by the width of all regions).

Parameters:

first_interface_position – The position of the left-most coordinate along the axis, only necessary for modeling a hollow sphere geometry [m]

Returns:

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

with_timestep_control(timestep_control: TimestepControl, to: float = 1.7976931348623157e+308)

Sets the timestep control options.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Parameters:
  • timestep_control – The new timestep control options

  • to – The upper time-limit for timestep_control.

Returns:

This DiffusionIsoThermalCalculation object

class tc_python.diffusion.DiffusionNonIsoThermalCalculation(calculation)

Bases: AbstractCalculation

Configuration for a non-isothermal diffusion calculation.

add_console_command(console_command: str)

Registers a DICTRA Console Mode command for execution. These commands are executed after all other configuration directly before the calculation starts to run. All commands are stored and used until explicitly deleted using tc_python.diffusion.DiffusionNonIsoThermalCalculation.remove_all_console_commands.

Parameters:

console_command – The DICTRA Console Mode command

Returns:

This DiffusionNonIsoThermalCalculation 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 DICTRA-commands directly in the engine, it may hang the program in case of spelling mistakes (e.g. forgotten parenthesis, …).

add_region(region: Region)

Adds a region to the calculation. Regions are always added in the simulation domain from left to right.

If you want to replace an already added region, call remove_all_regions(), and add the regions that you want to keep.

Warning

Regions must have unique names.

Parameters:

region – The region to be added

Returns:

This DiffusionNonIsoThermalCalculation object

calculate(timeout_in_minutes: float = 0.0) DiffusionCalculationResult

Runs the diffusion calculation.

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

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

remove_all_console_commands()

Removes all previously added Console Mode commands.

Returns:

This DiffusionNonIsoThermalCalculation object

remove_all_regions()

Removes all previously added regions.

Returns:

This DiffusionNonIsoThermalCalculation object

set_simulation_time(simulation_time: float)

Sets the simulation time.

Parameters:

simulation_time – The simulation time [s]

Returns:

This DiffusionNonIsoThermalCalculation object

with_cylindrical_geometry(first_interface_position: float = 0.0)

Sets geometry to cylindrical, corresponds to an infinitely long cylinder of a certain radius.

Default: A planar geometry

Note

With a cylindrical or spherical geometry, the system’s zero coordinate (left boundary) is at the centre of the cylinder or sphere by default. By specifying the first_interface_position, a different left-most coordinate can be defined. This allows to model a tube or a hollow sphere geometry. The highest coordinate (right boundary) is defined by the cylinder or sphere radius (i.e. by the width of all regions).

Parameters:

first_interface_position – The position of the left-most coordinate along the axis, only necessary for modeling a tube geometry [m]

Returns:

This DiffusionNonIsoThermalCalculation object

with_left_boundary_condition(boundary_condition: BoundaryCondition, to: float = 1.7976931348623157e+308)

Defines the boundary condition on the left edge of the system.

Default: A closed-system boundary condition.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Note

You can specify time-dependent boundary conditions by calling with_left_boundary_condition() many times, with different values of the “to” parameter.

Examples:

  • with_left_boundary_condition(BoundaryCondition.closed_system(), to=100)

  • with_left_boundary_condition(BoundaryCondition.mixed_zero_flux_and_activity().set_activity_for_element(“C”, surface_activity), to=500)

  • with_left_boundary_condition(BoundaryCondition.closed_system())

This example sets an closed-system-boundary-condition from start up to 100s and a activity-boundary-condition from 100s to 500s and finally a closed-system-boundary-condition from 500s to the end of simulation.

Parameters:
  • boundary_condition – The boundary condition

  • to – The upper time-limit for boundary_condition.

Returns:

This DiffusionNonIsoThermalCalculation object

with_options(options: Options, to: float = 1.7976931348623157e+308)

Sets the general simulation conditions.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Parameters:
  • options – The general simulation conditions

  • to – The upper time-limit for options.

Returns:

This DiffusionNonIsoThermalCalculation object

with_planar_geometry()

Sets geometry to planar.

This is default.

Returns:

This DiffusionNonIsoThermalCalculation object

with_reference_state(element: 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:
  • element – The name of the element

  • 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 DiffusionNonIsoThermalCalculation object

with_right_boundary_condition(boundary_condition: BoundaryCondition, to: float = 1.7976931348623157e+308)

Defines the boundary condition on the right edge of the system.

Default: A closed-system boundary condition

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Note

You can specify time-dependent boundary conditions by calling with_right_boundary_condition() many times, with different values of the “to” parameter.

Examples:

  • with_right_boundary_condition(BoundaryCondition.closed_system(), to=100)

  • with_right_boundary_condition(BoundaryCondition.mixed_zero_flux_and_activity().set_activity_for_element(“C”, surface_activity), to=500)

  • with_right_boundary_condition(BoundaryCondition.closed_system())

This example sets an closed-system-boundary-condition from start up to 100s and a activity-boundary-condition from 100s to 500s and finally a closed-system-boundary-condition from 500s to the end of simulation.

Parameters:
  • boundary_condition – The boundary condition

  • to – The upper time-limit for boundary_condition.

Returns:

This DiffusionNonIsoThermalCalculation object

with_solver(solver: Solver, to: float = 1.7976931348623157e+308)

Sets the solver to use (Classic, Homogenization or Automatic). Default is Automatic.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Parameters:
  • solver – The solver to use

  • to – The upper time-limit for solver.

Returns:

This DiffusionNonIsoThermalCalculation object

with_spherical_geometry(first_interface_position: float = 0.0)

Sets geometry to spherical, corresponds to a sphere with a certain radius.

Default: A spherical geometry

Note

With a cylindrical or spherical geometry, the system’s zero coordinate (left boundary) is at the centre of the cylinder or sphere by default. By specifying the first_interface_position, a different left-most coordinate can be defined. This allows to model a tube or a hollow sphere geometry. The highest coordinate (right boundary) is defined by the cylinder or sphere radius (i.e. by the width of all regions).

Parameters:

first_interface_position – The position of the left-most coordinate along the axis, only necessary for modeling a hollow sphere geometry [m]

Returns:

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

with_temperature_profile(temperature_profile: TemperatureProfile)

Sets the temperature profile to use with this calculation.

Parameters:

temperature_profile – The temperature profile object (specifying time / temperature points)

Returns:

This DiffusionNonIsoThermalCalculation object

with_timestep_control(timestep_control: TimestepControl, to: float = 1.7976931348623157e+308)

Sets the timestep control options.

It is possible specify the upper time-point for which this setting is valid using the parameter “to”.

Default: The end of the simulation.

Parameters:
  • timestep_control – The new timestep control options

  • to – The upper time-limit for timestep_control.

Returns:

This DiffusionNonIsoThermalCalculation object

class tc_python.diffusion.DoubleGeometricGrid(no_of_points: int = 50, lower_geometrical_factor: float = 1.1, upper_geometrical_factor: float = 0.9)

Bases: CalculatedGrid

Represents a double geometric grid.

get_lower_geometrical_factor() float

Returns the lower geometrical factor (for the left half).

Returns:

The lower geometrical factor

get_no_of_points() int

Returns number of grid points.

Returns:

The number of grid points

get_type() str

Type of the grid.

Returns:

The type of the grid

get_upper_geometrical_factor()

Returns the upper geometrical factor (for the right half).

Returns:

The upper geometrical factor

set_lower_geometrical_factor(geometrical_factor: float = 1.1)

Sets the lower (left half) geometrical factor.

Note

A geometrical factor of larger than one yields a higher density of grid points at the lower end of the half and vice versa for a factor smaller than one.

Parameters:

geometrical_factor – The geometrical factor for the left half

Returns:

This DoubleGeometricGrid object

set_no_of_points(no_of_points: int = 50)

Sets the number of grid points.

Parameters:

no_of_points – The number of points

Returns:

This DoubleGeometricGrid object

set_upper_geometrical_factor(geometrical_factor: float = 0.9)

Sets the upper (right half) geometrical factor.

Note

A geometrical factor of larger than one yields a higher density of grid points at the lower end of the half and vice versa for a factor smaller than one.

Parameters:

geometrical_factor – The geometrical factor for the right half

Returns:

This DoubleGeometricGrid object

class tc_python.diffusion.ElementProfile

Bases: AbstractElementProfile

Factory class providing objects for configuring a step, function or linear initial concentration profile.

classmethod constant(value: float)

Factory method that creates a new constant initial concentration profile.

Parameters:

value – The constant composition in the region. [unit as defined in CompositionProfile].

Returns:

A new ConstantProfile object

classmethod funct(dictra_console_mode_function: str)

Factory method that creates a new initial concentration profile defined by a function in DICTRA Console Mode syntax.

Parameters:

dictra_console_mode_function – The function, expressed in DICTRA Console Mode syntax.

Returns:

A new FunctionProfile object

Note

This is an advanced feature, preferably a complex concentration profile should be generated using third party libraries and added to the simulation using tc_python.diffusion.PointByPointGrid.

classmethod linear(start_value: float, end_value: float)

Factory method that creates a new linear initial concentration profile.

Parameters:
  • start_value – Composition at the left side of the region [unit as defined in CompositionProfile].

  • end_value – Composition at the right side of the region [unit as defined in CompositionProfile].

Returns:

A new LinearProfile object

classmethod step(lower_boundary: float, upper_boundary: float, step_at: float)

Factory method that creates a new initial concentration profile with a step at the specified distance, otherwise the composition is constant at the specified values.

Parameters:
  • lower_boundary – Composition before the step [unit as defined in CompositionProfile].

  • upper_boundary – Composition after the step [unit as defined in CompositionProfile].

  • step_at – The distance where the step should be [m].

Returns:

A new StepProfile object

class tc_python.diffusion.FixFluxValue

Bases: BoundaryCondition

get_type() str

The type of the boundary condition.

Returns:

The type

set_flux(element_name: str, J: str = '0', to_time: float = 1.7976931348623157e+308)

Enter functions that yield the flux times the molar volume for the specified element. May be a function of time, temperature and pressure: J(T,P,TIME).

Parameters:
  • element_name – The name of the element

  • J – the function J(T,P,TIME)

  • to_time – The max-time for which the flux function is used.

class tc_python.diffusion.FixedCompositions(unit_enum: Unit = Unit.MASS_PERCENT)

Bases: BoundaryCondition

Represents a boundary having fixed composition values.

get_type() str

The type of the boundary condition.

Returns:

The type

set_composition(element_name: str, value: float)

Sets the composition for the specified element.

Note

The boundary composition needs to be specified for each element.

Parameters:
  • element_name – The name of the element

  • value – The composition value [unit according to the constructor parameter]

class tc_python.diffusion.FunctionProfile(dictra_console_mode_function: str)

Bases: ElementProfile

Creates an initial concentration profile defined by a function in DICTRA Console Mode syntax.

Note

This is an advanced feature, preferably a complex concentration profile should be generated using third party libraries and added to the simulation using tc_python.diffusion.PointByPointGrid.

get_type() str

The type of the element profile.

Returns:

The type

class tc_python.diffusion.GeneralLowerHashinShtrikman

Bases: HomogenizationFunctions

General lower Hashin-Shtrikman bounds: the outermost shell consists of the phase with the most sluggish kinetics.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

class tc_python.diffusion.GeneralLowerHashinShtrikmanExcludedPhase(excluded_phases: List[str] = [])

Bases: HomogenizationFunctions

General lower Hashin-Shtrikman bounds: the outermost shell consists of the phase with the most sluggish kinetics.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

The excluded phases are not considered when evaluating what phase has the most sluggish kinetics.

class tc_python.diffusion.GeneralUpperHashinShtrikman

Bases: HomogenizationFunctions

General upper Hashin-Shtrikman bounds: the innermost shell consists of the phase with the most sluggish kinetics.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

class tc_python.diffusion.GeneralUpperHashinShtrikmanExcludedPhase(excluded_phases: List[str] = [])

Bases: HomogenizationFunctions

General upper Hashin-Shtrikman bounds: the innermost shell consists of the phase with the most sluggish kinetics.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

The excluded phases are not considered when evaluating what phase has the most sluggish kinetics.

class tc_python.diffusion.GeometricGrid(no_of_points: int = 50, geometrical_factor: float = 1.1)

Bases: CalculatedGrid

Represents a geometric grid.

get_geometrical_factor() float

Returns the geometrical factor.

Returns:

The geometrical factor

get_no_of_points() int

Returns the number of grid points.

Returns:

The number of grid points

get_type() str

Returns the type of grid.

Returns:

The type

set_geometrical_factor(geometrical_factor: float = 1.1)

Sets the geometrical factor.

Note

A geometrical factor larger than one yields a higher density of grid points at the lower end of the region and a factor smaller than one yields a higher density of grid points at the upper end of the region.

Parameters:

geometrical_factor – The geometrical factor

Returns:

This GeometricGrid object

set_no_of_points(no_of_points: int = 50)

Sets the number of grid points.

Parameters:

no_of_points – The number of points

Returns:

This GeometricGrid object

class tc_python.diffusion.GridPoint(distance: float)

Bases: object

Represents a grid point, this is used in combination with grids of the type tc_python.diffusion.PointByPointGrid.

add_composition(element: str, value: float)

Adds a composition for the specified element to the grid point.

Parameters:
  • element – The element

  • value – The composition value [unit as defined for the grid]

Returns:

This GridPoint object

class tc_python.diffusion.HashinShtrikmanBoundMajority

Bases: HomogenizationFunctions

Hashin-Shtrikman bounds with majority phase as matrix phase: the outermost shell consists of the phase with the highest local volume fraction.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

class tc_python.diffusion.HashinShtrikmanBoundMajorityExcludedPhase(excluded_phases: List[str] = [])

Bases: HomogenizationFunctions

Hashin-Shtrikman bounds with majority phase as matrix phase: the outermost shell consists of the phase with the highest local volume fraction.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

The excluded phases are not considered when evaluating what phase has the most sluggish kinetics.

class tc_python.diffusion.HashinShtrikmanBoundPrescribed(matrix_phase: str)

Bases: HomogenizationFunctions

Hashin-Shtrikman bounds with prescribed phase as matrix phase: the outermost shell consists of the prescribed phase.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

class tc_python.diffusion.HashinShtrikmanBoundPrescribedExcludedPhase(matrix_phase: str, excluded_phases: List[str] = [])

Bases: HomogenizationFunctions

class tc_python.diffusion.HomogenizationFunction(value)

Bases: Enum

Homogenization function used for the homogenization solver. Many homogenization functions are based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase. Default: RULE_OF_MIXTURES (i.e. upper Wiener bounds)

GENERAL_LOWER_HASHIN_SHTRIKMAN = 0

General lower Hashin-Shtrikman bounds: the outermost shell consists of the phase with the most sluggish kinetics.

GENERAL_UPPER_HASHIN_SHTRIKMAN = 1

General upper Hashin-Shtrikman bounds: the innermost shell consists of the phase with the most sluggish kinetics.

HASHIN_SHTRIKMAN_BOUND_MAJORITY = 2

Hashin-Shtrikman bounds with majority phase as matrix phase: the outermost shell consists of the phase with the highest local volume fraction.

INVERSE_RULE_OF_MIXTURES = 4

Lower Wiener bounds: the geometrical interpretation are continuous layers of each phase orthogonal to the direction of diffusion

RULE_OF_MIXTURES = 3

Upper Wiener bounds: the geometrical interpretation are continuous layers of each phase parallel with the direction of diffusion

class tc_python.diffusion.HomogenizationFunctions

Bases: object

classmethod general_lower_hashin_shtrikman()

Factory method that creates a new homogenization function of the type GeneralLowerHashinShtrikman.

General lower Hashin-Shtrikman bounds: the outermost shell consists of the phase with the most sluggish kinetics.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

Returns:

A new GeneralLowerHashinShtrikman object

classmethod general_lower_hashin_shtrikman_excluded_phase(excluded_phases: List[str] = [])

Factory method that creates a new homogenization function of the type GeneralLowerHashinShtrikmanExcludedPhase.

General lower Hashin-Shtrikman bounds: the outermost shell consists of the phase with the most sluggish kinetics.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase. The excluded phases are not considered when evaluating what phase has the most sluggish kinetics.

Parameters:

excluded_phases – The excluded phases

Returns:

A new GeneralLowerHashinShtrikmanExcludedPhase object

classmethod general_upper_hashin_shtrikman()

Factory method that creates a new homogenization function of the type GeneralUpperHashinShtrikman.

General upper Hashin-Shtrikman bounds: the innermost shell consists of the phase with the most sluggish kinetics.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

Returns:

A new GeneralUpperHashinShtrikman object

classmethod general_upper_hashin_shtrikman_excluded_phase(excluded_phases: List[str] = [])

Factory method that creates a new homogenization function of the type GeneralUpperHashinShtrikmanExcludedPhase.

General upper Hashin-Shtrikman bounds: the innermost shell consists of the phase with the most sluggish kinetics.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase. The excluded phases are not considered when evaluating what phase has the most sluggish kinetics.

Parameters:

excluded_phases – The excluded phases

Returns:

A new GeneralUpperHashinShtrikmanExcludedPhase object

classmethod hashin_shtrikman_bound_majority()

Factory method that creates a new homogenization function of the type HashinShtrikmanBoundMajority.

Hashin-Shtrikman bounds with majority phase as matrix phase: the outermost shell consists of the phase with the highest local volume fraction.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

Returns:

A new HashinShtrikmanBoundMajority object

classmethod hashin_shtrikman_bound_majority_excluded_phase(excluded_phases: List[str] = [])

Factory method that creates a new homogenization function of the type HashinShtrikmanBoundMajorityExcludedPhase.

Hashin-Shtrikman bounds with majority phase as matrix phase: the outermost shell consists of the phase with the highest local volume fraction. Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase. The excluded phases are not considered when evaluating what phase has the most sluggish kinetics.

Parameters:

excluded_phases – The excluded phases

Returns:

A new HashinShtrikmanBoundMajorityExcludedPhase object

classmethod hashin_shtrikman_bound_prescribed(matrix_phase: str)

Factory method that creates a new homogenization function of the type HashinShtrikmanBoundPrescribed.

Hashin-Shtrikman bounds with prescribed phase as matrix phase: the outermost shell consists of the prescribed phase.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase.

Parameters:

matrix_phase – The matrix phase

Returns:

A new HashinShtrikmanBoundPrescribed object

classmethod hashin_shtrikman_bound_prescribed_excluded_phase(matrix_phase: str, excluded_phases: List[str] = [])

Factory method that creates a new homogenization function of the type HashinShtrikmanBoundPrescribedExcludedPhase.

Hashin-Shtrikman bounds with prescribed phase as matrix phase: the outermost shell consists of the prescribed phase.

Based on a variant of the Hashin-Shtrikman bounds, their geometrical interpretation are concentric spherical shells of each phase. The excluded phases are not considered when evaluating what phase has the most sluggish kinetics.

Parameters:
  • matrix_phase – The matrix phase

  • excluded_phases – The excluded phases

Returns:

A new HashinShtrikmanBoundPrescribedExcludedPhase object

classmethod inverse_rule_of_mixtures()

Factory method that creates a new homogenization function of the type InverseRuleOfMixtures.

Lower Wiener bounds: the geometrical interpretation are continuous layers of each phase orthogonal to the direction of diffusion.

Returns:

A new InverseRuleOfMixtures object

classmethod inverse_rule_of_mixtures_excluded_phase(excluded_phases: List[str] = [])

Factory method that creates a new homogenization function of the type InverseRuleOfMixturesExcludedPhase.

Lower Wiener bounds: the geometrical interpretation are continuous layers of each phase orthogonal to the direction of diffusion. Excluded phases are not considered in the diffusion calculations.

Parameters:

excluded_phases – The excluded phases

Returns:

A new InverseRuleOfMixturesExcludedPhase object

classmethod labyrinth_factor_f(matrix_phase: str)

Factory method that creates a new homogenization function of the type LabyrinthFactorF.

The labyrinth factor functions implies that all diffusion takes place in a single continuous matrix phase. The impeding effect on diffusion by phases dispersed in the matrix phase is taken into account by multiplying the flux with the volume fraction of the matrix phase.

Parameters:

matrix_phase – The matrix phase

Returns:

A new LabyrinthFactorF object

classmethod labyrinth_factor_f2(matrix_phase: str)

Factory method that creates a new homogenization function of the type LabyrinthFactorF2.

The labyrinth factor functions implies that all diffusion takes place in a single continuous matrix phase. The impeding effect on diffusion by phases dispersed in the matrix phase is taken into account by multiplying the flux with the volume fraction of the matrix phase squared.

Parameters:

matrix_phase – The matrix phase

Returns:

A new LabyrinthFactorF2 object

classmethod rule_of_mixtures()

Factory method that creates a new homogenization function of the type RuleOfMixtures.

Upper Wiener bounds: the geometrical interpretation are continuous layers of each phase parallel with the direction of diffusion.

Returns:

A new RuleOfMixtures object

classmethod rule_of_mixtures_excluded_phase(excluded_phases: List[str] = [])

Factory method that creates a new homogenization function of the type RuleOfMixturesExcludedPhase.

Upper Wiener bounds: the geometrical interpretation are continuous layers of each phase parallel with the direction of diffusion. Excluded phases are not considered in the diffusion calculations.

Parameters:

excluded_phases – The excluded phases

Returns:

A new RuleOfMixturesExcludedPhase object

class tc_python.diffusion.HomogenizationSolver

Bases: Solver

Solver using the Homogenization model.

Note

This solver always uses the homogenization model, even if all regions have only one phase. The solver is significantly slower than the Classic model. Use the tc_python.diffusion.AutomaticSolver instead if you do not need that behavior.

disable_global_minimization()

Disables global minimization to be used in equilibrium calculations. Default: Disabled

Note

In general, using global minimization significantly increases the simulation time, but there is also a significantly reduced risk for non-converged equilibrium calculations.

Returns:

A new HomogenizationSolver object

disable_interpolation_scheme()

Configures the simulation not use any interpolation scheme. Default: To use the logarithmic interpolation scheme with 10000 discretization steps

Note

The homogenization scheme can be switched on by using with_linear_interpolation_scheme or with_logarithmic_interpolation_scheme.

enable_global_minimization()

Enables global minimization to be used in equilibrium calculations. Default: Disabled

Note

In general, using global minimization significantly increases the simulation time, but there is also a significantly reduced risk for non-converged equilibrium calculations.

Returns:

A new HomogenizationSolver object

get_type() str

The type of solver.

Returns:

The type

set_fraction_of_free_memory_to_use(fraction: float)

Sets the maximum fraction of free physical memory to be used by the interpolation scheme. Default: 1 / 10 of the free physical memory

Parameters:

fraction – The maximum free physical memory fraction to be used

Returns:

A new HomogenizationSolver object

set_memory_to_use(memory_in_megabytes: float)

Sets the maximum physical memory in megabytes to be used by the interpolation scheme. Default: 1000 MBytes of the free physical memory

Parameters:

memory_in_megabytes – The maximum physical memory to be used

Returns:

A new HomogenizationSolver object

with_function(homogenization_function: HomogenizationFunctions)

Sets the homogenization function used by the homogenization model.

Parameters:

homogenization_function – The homogenization function used by the homogenization model

Returns:

A new HomogenizationSolver object

with_linear_interpolation_scheme(steps: int = 10000)

Configures the simulation to use the linear interpolation scheme. Default: To use the logarithmic interpolation scheme with 10000 discretization steps

Parameters:

steps – The number of discretization steps in each dimension

Returns:

A new HomogenizationSolver object

with_logarithmic_interpolation_scheme(steps: int = 10000)

Configures the simulation to use the linear interpolation scheme. Default: To use the logarithmic interpolation scheme with 10000 discretization steps

Parameters:

steps – The number of discretization steps in each dimension

Returns:

A new HomogenizationSolver object

class tc_python.diffusion.InverseRuleOfMixtures

Bases: HomogenizationFunctions

Lower Wiener bounds: the geometrical interpretation are continuous layers of each phase orthogonal to the direction of diffusion.

class tc_python.diffusion.InverseRuleOfMixturesExcludedPhase(excluded_phases: List[str] = [])

Bases: HomogenizationFunctions

Lower Wiener bounds: the geometrical interpretation are continuous layers of each phase orthogonal to the direction of diffusion.

Excluded phases are not considered in the diffusion calculations.

class tc_python.diffusion.LabyrinthFactorF(matrix_phase: str)

Bases: HomogenizationFunctions

The labyrinth factor functions implies that all diffusion takes place in a single continuous matrix phase. The impeding effect on diffusion by phases dispersed in the matrix phase is taken into account by multiplying the flux with the volume fraction of the matrix phase.

class tc_python.diffusion.LabyrinthFactorF2(matrix_phase: str)

Bases: HomogenizationFunctions

The labyrinth factor functions implies that all diffusion takes place in a single continuous matrix phase. The impeding effect on diffusion by phases dispersed in the matrix phase is taken into account by multiplying the flux with the volume fraction of the matrix phase squared.

class tc_python.diffusion.LinearGrid(no_of_points: int = 50)

Bases: CalculatedGrid

Represents an equally spaced grid.

get_no_of_points() int

Returns the number of grid points.

Returns:

The number of grid points

get_type() str

Type of the grid.

Returns:

The type

set_no_of_points(no_of_points: int = 50)

Sets the number of grid points.

Parameters:

no_of_points – The number of points

Returns:

This LinearGrid object

class tc_python.diffusion.LinearProfile(start_value: float, end_value: float)

Bases: ElementProfile

Represents a linear initial concentration profile.

get_type() str

The type of the element profile.

Returns:

The type

class tc_python.diffusion.MixedZeroFluxAndActivity

Bases: BoundaryCondition

Represents a boundary having zero-flux as well as fixed-activity conditions.

Default: On that boundary for every element without an explicitly defined condition, a zero-flux boundary condition is used.

get_type() str

The type of the boundary condition.

Returns:

The type

set_activity_for_element(element_name: str, activity: str, to_time: float = 1.7976931348623157e+308)

Sets an activity expression for an element at the boundary. Enter a formula that the software evaluates during the calculation.

The formula can be:

  • a function of the variable TIME

  • a constant

The formula must be written with these rules:

  • a number must begin with a number (not a .)

  • a number must have a dot or an exponent (E)

The operators +, -, *, /, ** (exponentiation) can be used and with any level of parenthesis. As shown, the following operators must be followed by open and closed parentheses ()

  • SQRT(X) is the square root

  • EXP(X) is the exponential

  • LOG(X) is the natural logarithm

  • LOG10(X) is the base 10 logarithm

  • SIN(X), COS(X), TAN(X), ASIN(X), ACOS(X), ATAN(X)

  • SINH(X), COSH(X), TANH(X), ASINH(X), ACOSH(X), ATANH(X)

  • SIGN(X)

  • ERF(X) is the error function

Default: the expression entered is used for the entire simulation.

Parameters:
  • element_name – The name of the element

  • activity – The activity

  • to_time – The max-time for which the activity is used.

set_zero_flux_for_element(element_name: str)

Sets a zero-flux condition for an element at the boundary. Default for all elements at the boundary without an explicitly defined condition

Parameters:

element_name – The name of the element

class tc_python.diffusion.Options

Bases: object

General simulation conditions for the diffusion calculations.

disable_forced_starting_values_in_equilibrium_calculations()

Disables forced starting values for the equilibrium calculations. The default is ‘enable_automatic_forced_starting_values_in_equilibrium_calculations’.

Returns:

This Options object

disable_save_results_to_file()

Disables the saving of results to file during the simulation. Default: Saving of the results at every timestep

Returns:

This Options object

enable_automatic_forced_starting_values_in_eq_calculations()

Lets calculation engine decide if forced start values for the equilibrium calculations should be used. This is the default setting.

Returns:

This Options object

enable_forced_starting_values_in_equilibrium_calculations()

Enables forced start values for the equilibrium calculations. The default is ‘enable_automatic_forced_starting_values_in_equilibrium_calculations’.

Returns:

This Options object

enable_save_results_to_file(every_nth_step: int = -1)

Enables and configures saving of results to file during the simulation. They can be saved for every n-th or optionally for every timestep (-1). Default: Saving of the results at every timestep

Parameters:

every_nth_step-1 or a value ranging from 0 to 99

Returns:

This Options object

enable_time_integration_method_automatic()

Enables automatic selection of integration method. This is the default method.

Returns:

This Options object

enable_time_integration_method_euler_backwards()

Enables Euler backwards integration. The default method is enable_time_integration_method_automatic.

Note

This method is more stable but less accurate and may be necessary if large fluctuations occur in the profiles.

Returns:

This Options object

enable_time_integration_method_trapezoidal()

Enables trapezoidal integration.

Note

If large fluctuations occur in the profiles, it may be necessary to use the more stable but less accurate Euler backwards method.

Returns:

This Options object

set_default_driving_force_for_phases_allowed_to_form_at_interf(driving_force: float = 1e-05)

Sets the default required driving force for phases allowed to form at the interfaces. Default: 1.0e-5

Note

The required driving force (evaluated as DGM(ph)) is used for determining whether an inactive phase is stable, i.e. actually formed. DGM represents the driving force normalized by RT and is dimensionless.

Parameters:

driving_force – The driving force (DGM(ph)) [-]

Returns:

This Options object

class tc_python.diffusion.PointByPointGrid(unit_enum: Unit = Unit.MASS_PERCENT)

Bases: AbstractGrid

Represents a point-by-point grid. This is setting the grid and the compositions at once, it is typically used to enter a measured composition profile or the result from a previous calculation.

Note

If a point-by-point grid is used, it is not necessary to specify the grid and composition profile separately.

add_point(grid_point: GridPoint)

Adds a grid point to the grid.

Parameters:

grid_point – The grid point

Returns:

This PointByPointGrid object

get_type() str

Type of the grid.

Returns:

The type

class tc_python.diffusion.Region(name: str)

Bases: object

Represents a region of the simulation domain that can contain more that one phase.

Note

The first added phase represents the matrix phase, while all later added phases are spheriod phases, i.e. precipitate phases.

add_phase(phase_name: str, is_matrix_phase: bool = False)

Adds a phase to the region, each region must contain at least one phase.

Note

Normally the matrix phase and the precipitate phases are automatically chosen based on the presence of all profile elements in the phase and if it has diffusion data. If multiple phases have equal properties, the phase that was added first is chosen. The matrix phase can be explicitly set by using is_matrix_phase=True.

Note

If multiple phases are added to a region, the homogenization model is applied. That means that average properties of the local phase mixture are used.

Parameters:
  • phase_name – The phase name

  • is_matrix_phase – If set to True this phase is explicitly set as matrix phase for the region, if no phase is set to True, the matrix phase is chosen automatically

Returns:

This Region object

add_phase_allowed_to_form_at_left_interface(phase_name: str, driving_force: float = 1e-05)

Adds a phase allowed to form at the left boundary of the region (an inactive phase). The phase will only appear at the interface as a new automatic region if the driving force to form it is sufficiently high.

Parameters:
  • phase_name – The phase name

  • driving_force – The driving force for the phase to form (DGM(ph))

Returns:

This Region object

add_phase_allowed_to_form_at_right_interface(phase_name: str, driving_force: float = 1e-05)

Adds a phase allowed to form at the right boundary of the region (an inactive phase). The phase will only appear at the interface as a new automatic region if the driving force to form it is sufficiently high.

Parameters:
  • phase_name – The phase name

  • driving_force – The driving force for the phase to form (DGM(ph))

Returns:

This Region object

remove_all_phases()

Removes all previously added phases from the region.

Returns:

This Region object

set_width(width: float)

Defined the width of the region.

Note

This method needs only to be used if a calculated grid has been defined (using with_grid()).

Parameters:

width – The width [m]

Returns:

This Region object

with_composition_profile(initial_compositions: CompositionProfile)

Defines the initial composition profiles for all elements in the region.

Note

This method needs only to be used if a calculated grid has been defined (using with_grid()).

Parameters:

initial_compositions – The initial composition profiles for all elements

Returns:

This Region object

with_grid(grid: CalculatedGrid)

Defines a calculated grid in the region. If measured composition profiles or the result from a previous calculation should be used, instead with_point_by_point_grid_containing_compositions() needs to be applied.

Note

The composition profiles need to be defined separately using with_composition_profile(), additionally the region width needs to be specified using set_width().

Parameters:

grid – The grid

Returns:

This Region object

with_point_by_point_grid_containing_compositions(grid: PointByPointGrid)

Defines a point-by-point grid in the region. This is setting the grid and the compositions at once, it is typically used to enter a measured composition profile or the result from a previous calculation. If the composition profile should be calculated (linear, geometric, …) with_grid() should be used instead.

Note

If a point-by-point grid is used, with_grid(), with_composition_profile() and set_width() are unnecessary and must not be used.

Parameters:

grid – The point-by-point grid

Returns:

This Region object

class tc_python.diffusion.RuleOfMixtures

Bases: HomogenizationFunctions

Upper Wiener bounds: the geometrical interpretation are continuous layers of each phase parallel with the direction of diffusion.

class tc_python.diffusion.RuleOfMixturesExcludedPhase(excluded_phases: List[str] = [])

Bases: HomogenizationFunctions

Upper Wiener bounds: the geometrical interpretation are continuous layers of each phase parallel with the direction of diffusion.

Excluded phases are not considered in the diffusion calculations.

class tc_python.diffusion.SimulationTime(value)

Bases: Enum

Specifying special time steps for the evaluation of diffusion results.

Note

These placeholders should be used because especially the actual last timestep will slightly differ from the specified end time of the simulation.

FIRST = 0

Represents the first timestep of the simulation

LAST = 1

Represents the last timestep of the simulation

class tc_python.diffusion.Solver

Bases: AbstractSolver

Factory class providing objects representing a solver.

classmethod automatic()

Factory method that creates a new automatic solver. This is the default solver and recommended for most applications.

Note

This solver uses the homogenization model if any region has more than one phase, otherwise it uses the classic model.

Returns:

A new AutomaticSolver object

classmethod classic()

Factory method that creates a new classic solver.

Note

This solver never switches to the homogenization model even if the solver fails to converge. Use the tc_python.diffusion.AutomaticSolver if necessary instead.

Returns:

A new ClassicSolver object

classmethod homogenization()

Factory method that creates a new homogenization solver.

Note

This solver always uses the homogenization model, even if all regions have only one phase. The solver is significantly slower than the Classic model. Use the tc_python.diffusion.AutomaticSolver instead if you do not need that behavior.

Returns:

A new HomogenizationSolver object

class tc_python.diffusion.StepProfile(lower_boundary: float, upper_boundary: float, step_at: float)

Bases: ElementProfile

Represents an initial constant concentration profile with a step at the specified position.

get_type() str

The type of the element profile.

Returns:

The type

class tc_python.diffusion.TimestepControl

Bases: object

Settings that control the time steps in the simulation.

disable_check_interface_position()

Disables checking of the interface position, i.e. the timesteps are not controlled by the phase interface displacement during the simulation. The default setting is :func:`enable_automatic_check_interface_position`.

Returns:

This TimestepControl object

enable_automatic_check_interface_position()

Lets calculation engine decide if checking of the interface position should be used. This is the default setting.

Returns:

This TimestepControl object

enable_check_interface_position()

Enables checking of the interface position, i.e. the timesteps are controlled by the phase interface displacement during the simulation. The default setting is :func:`enable_automatic_check_interface_position`.

Returns:

This TimestepControl object

set_initial_time_step(initial_time_step: float = 1e-07)

Sets the initial timestep. Default: 1.0e-7 s

Parameters:

initial_time_step – The initial timestep [s]

Returns:

This TimestepControl object

set_max_absolute_error(absolute_error: float = 1e-05)

Sets the maximum absolute error. Default: 1.0e-5

Parameters:

absolute_error – The maximum absolute error

Returns:

This TimestepControl object

set_max_relative_error(relative_error: float = 0.05)

Sets the maximum relative error. Default: 0.05

Parameters:

relative_error – The maximum relative error

Returns:

This TimestepControl object

set_max_timestep_allowed_as_percent_of_simulation_time(max_timestep_allowed_as_percent_of_simulation_time: float = 10.0)

The maximum timestep allowed during the simulation, specified in percent of the simulation time. Default: 10.0%

Parameters:

max_timestep_allowed_as_percent_of_simulation_time – The maximum timestep allowed [%]

Returns:

This TimestepControl object

set_max_timestep_increase_factor(max_timestep_increase_factor: float = 2.0)

Sets the maximum timestep increase factor. Default: 2

Note

For example, if 2 is entered the maximum time step is twice as long as the previous time step taken.

Parameters:

max_timestep_increase_factor – The maximum timestep increase factor

Returns:

This TimestepControl object

set_smallest_time_step_allowed(smallest_time_step_allowed: float = 1e-07)

Sets the smallest time step allowed during the simulation. This is required when using the automatic procedure to determine the time step. Default: 1.0e-7 s

Parameters:

smallest_time_step_allowed – The smalles timestep allowed [s]

Returns:

This TimestepControl object

class tc_python.diffusion.Unit(value)

Bases: Enum

Represents a composition unit.

MASS_FRACTION = 2

Mass fraction.

MASS_PERCENT = 3

Mass percent.

MOLE_FRACTION = 0

Mole fraction.

MOLE_PERCENT = 1

Mole percent.

U_FRACTION = 4

U fraction