simu

Define and load diffusion simulation.

class simu.Simulation(ref)

Bases: AlloySystem

Thermodynamic system, simulation conditions, simulation results.

This is a base class that does some pre-processing and provides methods to set up simulation conditions, run simulation and plot the results.

It is possible to create a new simulation directly with this class, in which case the setup methods have to be called by the user. This provides the possibility of changing the system properties and simulation conditions in a user script, with functions not provided by this class (or the parent alloy_system.AlloySystem). Note that this should be done with great care, as the custom modifications may cause unexpected issues and will not be recorded in the log file.

The recommended way to create a simulation is to use NewSimulation (new simulation) or ReadSimulation (read from log file), where the default setup methods will be called.

Also note that using ReadSimulation to load a simulation first created with Simulation and custom setup functions (instead of NewSimulation) may produce an inconsistent state.

This is a 1D version, with time-invariant space grid and time step.

Variables:

• x_profile (str) – Type of initial atom fraction profiles. See accepted values in make_profile().

• zstep (float) – Position of step along step profile in m (see doc in meshing.make_step_profile()).

• q (float) – Common ratio for geometric grid.

• x_left (dict of floats) – Initial atom fractions of independent constituents on left-hand side.

• x_right (dict of floats) – Initial atom fractions of independent constituents on right-hand side.

• yVa_profile (str) – Type of initial vacancy site fraction profile. See accepted values in make_profile().

• yVa_left (float) – Initial vacancy site fraction on left-hand side.

• yVa_right (float) – Initial vacancy site fraction on right-hand side.

• fp_profile (str) – Type of initial pore volume fraction profile. See accepted values in make_profile().

• fp_left (float) – Initial pore volume fraction on left-hand side.

• fp_right (float) – Initial pore volume fraction on right-hand side.

• stencil (str) – Discretization stencil. See accepted values in solvers.compute_resistance().

• title (str) – Title to be used in plots. See plots.make_plot_title().

• zmin (float) – Initial position of left-hand domain boundary (m).

• zmax (float) – Initial position of right-hand domain boundary (m).

• nz_init (int) – Number of steps in initial space grid.

• z_init (1D array) – Initial node positions. Ranges from 0 to zmax, size nz. This is where fluxes are evaluated.

• dz_init (1D array) – Initial space step, shape (nz - 1,).

• zm_init (1D array) – Initial midpoint positions, shape (nz - 1,). This is where composition variables are evaluated.

• geometry (str) – Domain geometry (planar, cylindrical or spherical).

• th (float) – Simulation time in h.

• ts (float) – Simulation time in s.

• dt_multiplier (float) – Factor by which default time step is multiplied (see add_time()).

• dt (float) – Time step size in s.

• nt (int) – Number of time steps (positions in time sequence), including 0.

• num_out (int) – Number of time steps where simulation results are stored and saved on file.

• saved_steps (list) – Steps for which simulation results are stored and saved on file.

• saved_times (list) – Times in h (rounded) for which simulation results are stored and saved on file.

• x_init (dict of 1D arrays) – Initial atom fraction profiles of independent constituents.

• yVa_init (1D array) – Initial vacancy site fraction profile.

• fm_init (1D array) – Initial pore volume fraction profile.

• cvar (composition_variables.CompositionVariables) – Composition variables (x, y, c, Vm, …).

• BC (dict) – Type of boundary condition (Dirichlet, Neumann) and corresponding values or expressions. See add_BC().

• res (dict) – Simulation results, nested dicts with syntax res[th][var][k].

• simres (results.SimulationResults) – Simulation results.

__init__(ref)

Class constructor.

Use alloy_system.AlloySystem constructor to define system parameters, then pre-process some simulation conditions. See para_io.read_parameter_file() for how input file is parsed.

Perform consistency checks: if lattice is ideal, custom initial vacancy and pore fraction profiles are not allowed (vacancy fraction profile will be set to equilibrium, pore fraction profile will be set to 0).

check_boundary_conditions()

Check that boundary conditions are consistent.

Make sure all expected constituents are present in the declared boundary conditions.

Call unit_check_BC_constituents() for the 4 conditions.

• Condition on x: expect to find all independent constituents.

• Condition on J: expect to find all atom constituents

unit_check_BC_constituents(var, expected)

Make sure all expected constituents are present in the BC.

unit_check_BC_values(var)

Make sure atom fractions are within accepted bounds.

check_grid_config()

Make sure grid-related input is consistent.

add_grid()

Add initial space grid.

Behavior controlled by the ‘grid’ parameter:

• ‘linear’: linear grid from zmin to zmax with size nz (zmax and nz must be included in parameter input file, zmin defaults to 0).

• ‘geo’: geometric grid from zmin to zmax with size nz and common ratio q (zmax and nz must be included in input file, zmin and q are optional).

• filename: read from sdir/filename using np.genfromtxt (zmin, zmax and nz are inferred from the grid).

add_time()

Add time step and number of time steps.

The time step dt is calculated to ensure the stability of explicit schemes, with a default Fourier number Fo = 0.4. The DT value is calculated from the initial concentration profile. The time step can be made smaller using the user-specified dt_multiplier (or nt_multiplier, see para_io.read_parameter_string()).

add_saved_steps()

Add list of time steps where simulation results will be saved to file.

The time steps are determined based on the num_out parameter.

add_profiles()

Add initial composition profiles.

Make atom fraction, vacancy site fraction and pore volume fraction profiles. These are then used to initialize cvar (see composition_variables.CompositionVariables).

add_x_profile()

Make initial atom fraction profile.

check_x_profile_from_file()

Prepare initial atom fraction profile.

Applies to profiles provided as file.

• Make sure the constituents in the initial atom fraction profile match the list of independent constituents declared in the input file.

• Enforce bounds on initial atom fractions and print warning.

check_x_profile_from_dicts()

Prepare initial atom fraction profile.

Applies to profiles provided as predefined types (see list in make_profile()).

• Make sure the constituents in the initial atom fraction profile match the list of independent constituents declared in the input file.

• Enforce bounds on initial atom fractions and print warning.

add_yVa_profile()

Make initial vacancy site fraction profile.

add_fm_profile()

Make initial metal volume fraction profile.

add_BC()

Add boundary conditions.

The keys of the BC attribute are ‘left’, ‘right’, ‘cvar_left’, ‘cvar_right’, ‘J_left’, ‘J_right’.

‘left’ and ‘right’ indicate the type of BC and can be either:

• ‘Dirichlet’: prescribed composition, if ‘xBC_left’ or ‘xBC_right’ is provided in params.

• ‘Neumann’: prescribed flux, if ‘JBC_left’ or ‘JBC_right’ is provided in params.

The other keys (‘cvar_left’, ‘cvar_right’, ‘J_left’, ‘J_right’) are functions of time (ex: (3*t + 2)**(1/2)) that return composition variables and flux arrays.

Defaults to 0-flux BC if no BC is specified in the input file.

make_JBC_fun(J_strings)

Make function that returns a boundary flux array.

The inner function returns a 1D array of fluxes, which include all atom constituents.

make_cBC_fun(x_strings)

Make function that returns a boundary composition variable.

The inner function returns a composition_variables.CompositionVariables instance. Two assumptions are made:

• vacancies are at equilibrium,

• the pore fraction is 0.

prepare_simulation_log()

Add simulation info to log.

run(show_completion=False, verbose=1)

Run diffusion simulation.

• Call to solvers.solver(). The function returns variables at saved_steps.

• These are printed to files, and stored in res dict. The keys of res are the time steps. The last time step can be accessed with -1 as key.

• A mass balance is performed (see add_mass_balance()).

Parameters:

• show_completion (bool, optional) – Print completion rate while simulation is running.

• verbose (int, optional) – Verbosity level, sets amount of information printed while simulation is running. Recommended values: 0 (less verbose) and 1 (more verbose). See solvers.solver() and solvers.remesh().

class simu.NewSimulation(ref)

Bases: Simulation

Create new simulation from input file.

This is the recommended way to create a new simulation. See Simulation for documentation on attributes and methods.

__init__(ref)

Class constructor.

Call Simulation constructor to define system parameters and pre-process simulation conditions. Then call Simulation methods to complete simulation setup.

class simu.ReadSimulationOld(ref)

Bases: Simulation

Create simulation from results file.

See Simulation for documentation on attributes and methods.

__init__(ref)

Class constructor.

Read input parameters, log and simulation results from output file. Check that the parameters in the output file coincide with those in the input file. A difference would mean that the input file has been modified after the simulation was run, and would be error-inducing. Then add attributes to complete initialization.

class simu.ReadSimulation(ref)

Bases: object

Create simulation from results file.

See Simulation for documentation on attributes and methods.

__init__(ref)

Class constructor.

Read log file of a previous simulation, extract useful attributes (see list in alloy_system.AlloySystem and Simulation) and make instance of results.SimulationResults. The latter organizes the results and exposes plot methods. The most useful plot methods are added as attributes of this class for ease of access (and backward compatibility).

simu.make_profile(profile, zmin, zmax, zm_init, val_left=None, val_right=None, sdir=None)

Make profile along distance axis.

Behavior determined by the ‘profile’ parameter:

• ‘step’ followed by a float argument: step profile with step at zstep (see doc in meshing.make_step_profile()) and values from val_left and val_right.

  If the argument is > 0.1, it is interpreted as a fraction of zrange -> zstep = zmin + argument*(zmax - zmin)

  If the argument is < 0.1, it is interpreted as zstep in m.

• ‘smooth step’ followed by a float argument: same with an error function instead of heaviside (see meshing.make_smooth_step_profile())

• ‘flat’: flat profile with values from val_left.

• filename: read from sdir/filename using np.genfromtxt

The input file must have the constituent profiles arranged by columns, with the constituent names on the first line. The size of the columns must match that of zm (i.e., nz - 1).

The ‘val_left’ and ‘val_right’ parameters are dicts with the independent constituents as keys.

simu.make_compo_string_from_xdict(x, dep)

Make label indicating an alloy composition.

Parameters:

• x (dict) – Atom fractions of independent constituents.

• dep (str) – Name of dependent constituent.

Returns:

A – Label indicating an alloy composition.

Return type:

str

Examples

>>> x = {'Cr': 0.2, 'Al': 0.062}
>>> dep = 'Ni'
>>> make_compo_string_from_xdict(x, dep)
'Ni-20Cr-6.2Al'

simu.make_plot_title(dep, profile_type, x_left, x_right, TC)

Make plot title.

Parameters:

• dep (str) – Name of dependent constituent.

• profile_type (str) – Type of initial atom fraction profile. See make_profile().

• x_left (dict of floats) – Initial atom fraction of dependent constituents on left hand side.

• x_right (dict of floats) – Initial atom fraction of dependent constituents on right hand side.

• TC (float) – Temperature in Celsius.

Returns:

title – Plot title.

Return type:

str