kawin.KWNBase
class kawin.PrecipitateBase(self, t0, tf, steps, phases = [‘beta’], linearTimeSpacing = False, elements = [‘solute’])
Base class for precipitation models
Note: currently only the Euler implementation is available, but
other implementations are planned to be added
Parameters
----------
t0 : float
Initial time in seconds
tf : float
Final time in seconds
steps : int
Number of time steps
phases : list (optional)
Precipitate phases (array of str)
If only one phase is considered, the default is ['beta']
linearTimeSpacing : bool (optional)
Whether to have time increment spaced linearly or logarithimically
Defaults to False
elements : list (optional)
Solute elements in system
Note: order of elements must correspond to order of elements set in Thermodynamics module
If binary system, then defualt is ['solute']
kawin.PrecipitateBase.phaseIndex(self, phase = None)
Returns index of phase in list
Parameters
----------
phase : str (optional)
Precipitate phase (defaults to None, which will return 0)
kawin.PrecipitateBase.reset(self)
Resets simulation results
This does not reset the model parameters, however, it will clear any stopping conditions
kawin.PrecipitateBase._resetArrays(self)
kawin.PrecipitateBase.save(self, filename, compressed = False, toCSV = False)
Save results into a numpy .npz or .csv format
Parameters
----------
filename : str
compressed : bool
If true, will save compressed .npz format
toCSV : bool
If true, will save to .csv
kawin.PrecipitateBase.load(filename)
Loads data
Parameters
----------
filename : str
Returns
-------
PrecipitateBase object
Note: this will only contain model outputs which can be used for plotting
kawin.PrecipitateBase._divideTimestep(self, i, dt)
Adds a new time step between t_i-1 and t_i, with new time being t_i-1 + dt
Parameters
----------
i : int
dt : float
Note: this must be smaller than t_i - t_i-1
kawin.PrecipitateBase.adaptiveTimeStepping(self, adaptive = True)
Sets if adaptive time stepping is used
Parameters
----------
adaptive : bool (optional)
Defaults to True
kawin.PrecipitateBase._calculateDT(self, i, fraction)
Calculates DT as a fraction of the total simulation time
kawin.PrecipitateBase._defaultConstraints(self)
Default values for contraints
kawin.PrecipitateBase.setConstraints(self, **kwargs)
Sets constraints
TODO: the following constraints are not implemented
maxDTFraction
maxRcritChange - this is somewhat implemented but disabled by default
Possible constraints:
---------------------
minRadius - minimum radius to be considered a precipitate (1e-10 m)
maxTempChange - maximum temperature change before lookup table is updated (only for Euler in binary case) (1 K)
maxDTFraction - maximum time increment allowed as a fraction of total simulation time (0.1)
minDTFraction - minimum time increment allowed as a fraction of total simulation time (1e-5)
checkTemperature - checks max temperature change (True)
maxNonIsothermalDT - maximum time step when temperature is changing (1 second)
checkPSD - checks maximum growth rate for particle size distribution (True)
maxDissolution - maximum relative volume fraction of precipitates allowed to dissolve in a single time step (0.01)
checkRcrit - checks maximum change in critical radius (False)
maxRcritChange - maximum change in critical radius (as a fraction) per single time step (0.01)
checkNucleation - checks maximum change in nucleation rate (True)
maxNucleationRateChange - maximum change in nucleation rate (on log scale) per single time step (0.5)
minNucleationRate - minimum nucleation rate to be considered for checking time intervals (1e-5)
checkVolumePre - estimates maximum volume change (True)
checkVolumePost - checks maximum calculated volume change (True)
maxVolumeChange - maximum absolute value that volume fraction can change per single time step (0.001)
checkComposition - checks maximum change in composition (True)
chekcCompositionPre - estimates maximum change in composition (False)
maxCompositionChange - maximum change in composition in single time step (0.01)
minNucleateDensity - minimum nucleate density to consider nucleation to have occurred (1e-5)
kawin.PrecipitateBase.setBetaBinary(self, functionType = 1)
Sets function for beta calculation in binary systems
If using a multicomponent system, this function will not do anything
Parameters
----------
functionType : int
ID for function
1 for implementation seen in Perez et al, 2008 (default)
2 for implementation similar to multicomponent systems
kawin.PrecipitateBase.setInitialComposition(self, xInit)
Parameters
xInit : float or array
Initial composition of parent matrix phase in atomic fraction
Use float for binary system and array of solutes for multicomponent systems
kawin.PrecipitateBase.setInterfacialEnergy(self, gamma, phase = None)
Parameters
----------
gamma : float
Interfacial energy between precipitate and matrix in J/m2
phase : str (optional)
Phase to input interfacial energy (defaults to first precipitate in list)
kawin.PrecipitateBase.resetAspectRatio(self, phase = None)
Resets aspect ratio variables of defined phase to default
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setSpherical(self, phase = None)
Sets precipitate shape to spherical for defined phase
Parameters
----------
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setAspectRatioNeedle(self, ratio=1, phase = None)
Consider specified precipitate phase as needle-shaped
with specified aspect ratio
Parameters
----------
ratio : float or function
Aspect ratio of needle-shaped precipitate
If float, must be greater than 1
If function, must take in radius as input and output float greater than 1
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setAspectRatioPlate(self, ratio=1, phase = None)
Consider specified precipitate phase as plate-shaped
with specified aspect ratio
Parameters
----------
ratio : float or function
Aspect ratio of needle-shaped precipitate
If float, must be greater than 1
If function, must take in radius as input and output float greater than 1
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setAspectRatioCuboidal(self, ratio=1, phase = None)
Consider specified precipitate phase as cuboidal-shaped
with specified aspect ratio
TODO: add cuboidal factor
Currently, I think this considers that the cuboidal factor is 1
Parameters
----------
ratio : float or function
Aspect ratio of needle-shaped precipitate
If float, must be greater than 1
If function, must take in radius as input and output float greater than 1
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setVmAlpha(self, Vm, atomsPerCell)
Molar volume for parent phase
Parameters
----------
Vm : float
Molar volume (m3 / mol)
atomsPerCell : int
Number of atoms in a unit cell
kawin.PrecipitateBase.setVaAlpha(self, Va, atomsPerCell)
Unit cell volume for parent phase
Parameters
----------
Va : float
Unit cell volume (m3 / unit cell)
atomsPerCell : int
Number of atoms in a unit cell
kawin.PrecipitateBase.setUnitCellAlpha(self, a, atomsPerCell)
Lattice parameter for parent phase (assuming cubic unit cell)
Parameters
----------
a : float
Lattice constant (m)
atomsPerCell : int
Number of atoms in a unit cell
kawin.PrecipitateBase.setVmBeta(self, Vm, atomsPerCell, phase = None)
Molar volume for precipitate phase
Parameters
----------
Vm : float
Molar volume (m3 / mol)
atomsPerCell : int
Number of atoms in a unit cell
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setVaBeta(self, Va, atomsPerCell, phase = None)
Unit cell volume for precipitate phase
Parameters
----------
Va : float
Unit cell volume (m3 / unit cell)
atomsPerCell : int
Number of atoms in a unit cell
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setUnitCellBeta(self, a, atomsPerCell, phase = None)
Lattice parameter for precipitate phase (assuming cubic unit cell)
Parameters
----------
a : float
Latice parameter (m)
atomsPerCell : int
Number of atoms in a unit cell
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setNucleationDensity(self, grainSize = 100, aspectRatio = 1, dislocationDensity = 5e12, bulkN0 = None)
Sets grain size and dislocation density which determines the available nucleation sites
Parameters
----------
grainSize : float (optional)
Average grain size in microns (default at 100um if this function is not called)
aspectRatio : float (optional)
Aspect ratio of grains (default at 1)
dislocationDensity : float (optional)
Dislocation density (m/m3) (default at 5e12)
bulkN0 : float (optional)
This allows for the use to override the nucleation site density for bulk precipitation
By default (None), this is calculated by the number of lattice sites containing a solute atom
However, for calibration purposes, it may be better to set the nucleation site density manually
kawin.PrecipitateBase._getNucleationDensity(self)
Calculates nucleation density
This is separated from setting nucleation density to
allow it to be called right before the simulation starts
kawin.PrecipitateBase.setNucleationSite(self, site, phase = None)
Sets nucleation site type for specified phase
If site type is grain boundaries, edges or corners, the phase morphology will be set to spherical and precipitate shape will depend on wetting angle
Parameters
----------
site : str
Type of nucleation site
Options are 'bulk', 'dislocations', 'grain_boundaries', 'grain_edges' and 'grain_corners'
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase._setGBfactors(self)
Calcualtes factors for bulk or grain boundary nucleation
This is separated from setting the nucleation sites to allow
it to be called right before simulation
kawin.PrecipitateBase._GBareaRemoval(self, p)
Returns factor to multiply radius by to give the equivalent radius of circles representing the area of grain boundary removal
Parameters
----------
p : int
Index for phase
kawin.PrecipitateBase.setParentPhases(self, phase, parentPhases)
Sets parent precipitates at which a precipitate can nucleate on the surface of
Parameters
----------
phase : str
Precipitate phase of interest that will nucleate
parentPhases : list
Phases that the precipitate of interest can nucleate on the surface of
kawin.PrecipitateBase.setGrainBoundaryEnergy(self, energy)
Grain boundary energy - this will decrease the critical radius as some grain boundaries will be removed upon nucleation
Parameters
----------
energy : float
GB energy in J/m2
Default upon initialization is 0.3
Note: GBenergy of 0 is equivalent to bulk precipitation
kawin.PrecipitateBase.setTheta(self, theta, phase = None)
This is a scaling factor for the incubation time calculation, default is 2
Incubation time is defined as 1 / \theta * \beta * Z^2
\theta differs by derivation. By default, this is set to 2 following the
Feder derivation. In the Wakeshima derivation, \theta is 4pi
Parameters
----------
theta : float
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setTemperature(self, temperature)
Sets isothermal temperature
Parameters
----------
temperature : float
Temperature in Kelvin
kawin.PrecipitateBase.setNonIsothermalTemperature(self, temperatureFunction)
Sets temperature as a function of time
Parameters
----------
temperatureFunction : function
Takes in time and returns temperature in K
kawin.PrecipitateBase.setTemperatureArray(self, times, temperatures)
Sets temperature as a function of time interpolating between the inputted times and temperatures
Parameters
----------
times : list
Time in hours for when the corresponding temperature is reached
temperatures : list
Temperatures in K to be reached at corresponding times
kawin.PrecipitateBase.setStrainEnergy(self, strainEnergy, phase = None, calculateAspectRatio = False)
Sets strain energy class to precipitate
kawin.PrecipitateBase._setupStrainEnergyFactors(self)
kawin.PrecipitateBase.setDiffusivity(self, diffusivity)
Parameters
----------
diffusivity : function taking
Composition and temperature (K) and returning diffusivity (m2/s)
Function must have inputs in this order: f(x, T)
For multicomponent systems, x is an array
kawin.PrecipitateBase.setInfinitePrecipitateDiffusivity(self, infinite, phase = None)
Sets whether to assuming infinitely fast or no diffusion in phase
Parameters
----------
infinite : bool
True will assume infinitely fast diffusion
False will assume no diffusion
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
Use 'all' to apply to all phases
kawin.PrecipitateBase.setDrivingForce(self, drivingForce, phase = None)
Parameters
----------
drivingForce : function
Taking in composition (at. fraction) and temperature (K) and return driving force (J/mol)
f(x, T) = dg, where x is float for binary and array for multicomponent
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setInterfacialComposition(self, composition, phase = None)
Parameters
----------
composition : function
Takes in temperature (K) and excess free energy (J/mol) and
returns a tuple of (matrix composition, precipitate composition)
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
The excess free energy term will be taken as the interfacial curvature and elastic energy contributions.
This will be a positive value, so the function should ensure that the excess free energy to reduce the driving force
If equilibrium cannot be solved, then the function should return (None, None) or (-1, -1)
kawin.PrecipitateBase.setThermodynamics(self, therm, phase = None, removeCache = False)
Parameters
----------
therm : Thermodynamics class
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.setSurrogate(self, surr, phase = None)
Parameters
----------
surr : Surrogate class
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.particleGibbs(self, radius, phase = None)
Returns Gibbs Thomson contribution of a particle given its radius
Parameters
----------
radius : float or array
Precipitate radius
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
kawin.PrecipitateBase.neglectEffectiveDiffusionDistance(self, neglect = True)
Whether or not to account for effective diffusion distance dependency on the supersaturation
By default, effective diffusion distance is considered
Parameters
----------
neglect : bool (optional)
If True (default), will assume effective diffusion distance is particle radius
If False, will calculate correction factor from Chen, Jeppson and Agren (2008)
kawin.PrecipitateBase.addStoppingCondition(self, variable, condition, value, phase = None, element = None, mode = ‘or’)
Adds condition to stop simulation when condition is met
Parameters
----------
variable : str
Variable to set condition for, options are
'Volume Fraction'
'Average Radius'
'Driving Force'
'Nucleation Rate'
'Precipitate Density'
condition : str
Operator for condition, options are
'greater than' or '>'
'less than' or '<'
value : float
Value for condition
phase : str (optional)
Phase to consider (defaults to first precipitate in list)
element : str (optional)
For 'Composition', element to consider for condition (defaults to first element in list)
mode : str (optional)
How the condition will be handled
'or' (default) - at least one condition in this mode needs to be met before stopping
'and' - all conditions in this mode need to be met before stopping
This will also record the times each condition is met
Example
model.addStoppingCondition('Volume Fraction', '>', 0.002, 'beta')
will add a condition to stop simulation when the volume fraction of the 'beta'
phase becomes greater than 0.002
kawin.PrecipitateBase.clearStoppingConditions(self)
Clears all stopping conditions
kawin.PrecipitateBase.printModelParameters(self)
Prints the model parameters
kawin.PrecipitateBase.setup(self)
Sets up hidden parameters before solving
Here it's just the nucleation density and the grain boundary nucleation factors
kawin.PrecipitateBase._printOutput(self, i)
Prints various terms at step i
kawin.PrecipitateBase.solve(self, verbose = False, vIt = 1000)
Solves the KWN model between initial and final time
Note: _calculateNucleationRate, _calculatePSD and _printOutput will need to be implemented in the child classes
Parameters
----------
verbose : bool (optional)
Whether to print current simulation terms every couple iterations
Defaults to False
vIt : int (optional)
If verbose is True, vIt is how many iterations will pass before printing an output
Defaults to 1000
kawin.PrecipitateBase._iterate(self, i)
Blank iteration function to be implemented in other classes
kawin.PrecipitateBase._nucleationRate(self, p, i)
Calculates nucleation rate at current timestep (normalized to number of nucleation sites)
This step is general to all systems except for how self._Beta is defined
Parameters
----------
p : int
Phase index (int)
i : int
Current iteration
dt : float
Current time increment
kawin.PrecipitateBase._noCheckDT(self, i)
Default for no adaptive time stepping
kawin.PrecipitateBase._noPostCheckDT(self, i)
Default for no adaptive time stepping
kawin.PrecipitateBase._checkDT(self, i)
Default time increment function if implement (which is no implementation)
kawin.PrecipitateBase._postCheckDT(self, i)
Default time increment function if implement (which is no implementation)
kawin.PrecipitateBase._noDrivingForce(self, p, i)
Set everything to 0 if there is no driving force for precipitation
kawin.PrecipitateBase._nucleateFreeEnergy(self, Rsph, p, i)
kawin.PrecipitateBase._Zeldovich(self, p, i)
kawin.PrecipitateBase._BetaBinary1(self, p, i)
kawin.PrecipitateBase._BetaBinary2(self, p, i)
kawin.PrecipitateBase._BetaMulti(self, p, i)
kawin.PrecipitateBase._incubationIsothermal(self, Z, p, i)
Incubation time for isothermal conditions
kawin.PrecipitateBase._incubationNonIsothermal(self, Z, p, i)
Incubation time for non-isothermal conditions
This must match isothermal conditions if the temperature is constant
Solve for integral(beta(t-t0)) from 0 to tau = 1/theta*Z(tau)^2
kawin.PrecipitateBase._setNucleateRadius(self, i)
kawin.PrecipitateBase.getTimeAxis(self, timeUnits=’s', bounds=None)
kawin.PrecipitateBase.plot(self, axes, variable, bounds = None, timeUnits = ’s', radius=‘spherical’, *args, **kwargs)
Plots model outputs
Parameters
----------
axes : Axis
variable : str
Specified variable to plot
Options are 'Volume Fraction', 'Total Volume Fraction', 'Critical Radius',
'Average Radius', 'Volume Average Radius', 'Total Average Radius',
'Total Volume Average Radius', 'Aspect Ratio', 'Total Aspect Ratio'
'Driving Force', 'Nucleation Rate', 'Total Nucleation Rate',
'Precipitate Density', 'Total Precipitate Density',
'Temperature' and 'Composition'
Note: for multi-phase simulations, adding the word 'Total' will
sum the variable for all phases. Without the word 'Total', the variable
for each phase will be plotted separately
bounds : tuple (optional)
Limits on the x-axis (float, float) or None (default, this will set bounds to (initial time, final time))
timeUnits : str (optional)
Plot time dependent variables per seconds ('s'), minutes ('m') or hours ('h')
radius : str (optional)
For non-spherical precipitates, plot the Average Radius by the -
Equivalent spherical radius ('spherical')
Short axis ('short')
Long axis ('long')
Note: Total Average Radius and Volume Average Radius will still use the equivalent spherical radius
*args, **kwargs - extra arguments for plotting