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 - checks maximum estimated 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) 
maxCompositionChange - maximum change in composition in single time step (0.01) 

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)

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._BetaBinary(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.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