# kawin.Surrogate

kawin.generateTrainingPoints(*arrays)

```
Creates all combinations of inputted arrays
Used for creating training points in composition space for
MulticomponentSurrogate
Parameters
----------
arrays - arrays along each dimension
Order of arrays should correspond to the order of elements when defining thermodynamic functions
```

kawin._filter_points(inputs, outputs, tol = 1e-3)

```
Filter set of input points such that the closest distance is above tolerance
This is to avoid non-positive definite training matrices when creating surrogate models
Parameters
----------
inputs : m x n matrix of floats
Input points of m observations in n-dimensional space
outputs : list of array of floats
Output points, each array must be m x n where
m is number of observations and n is dimensions of output
tol : float
Tolerance for distance between two input points
Outputs
-------
(filtered inputs, filtered outputs)
filtered inputs - array of input points
filtered outputs - array of output points
```

**class** kawin.BinarySurrogate(self, binaryThermodynamics = None, drivingForce = None, interfacialComposition = None, diffusivity = None, precPhase = None)

```
Handles surrogate models for driving force, interfacial composition and
diffusivity in a binary system
Parameters
----------
binaryThermodynamics - BinaryThermodynamics (optional)
Driving force and interfacial composition will be taken from this if not explicitly defined
If None, then drivingForce and interfacialComposition must be defined
drivingForce - function (optional)
Function will take in (composition, temperature) and return driving force,
where a positive value means that precipitation is favorable
interfacialComposition - function (optional)
Function will take in (temperature, excess gibbs free energy) and
return tuple (parent composition, precipitate composition) or (None, None) if precipitate is unstable
diffusivity - function (optional)
Function will take in (composition, temperature) and return diffusivity
precPhase : str (optional)
Precipitate phase to consider if binaryThermodynamics is defined
Note: if binaryThermodynamics is not defined, then drivingForce and
interfacial composition needs to be defined
```

kawin.BinarySurrogate.trainDrivingForce(self, comps, temperature, function=‘linear’, epsilon=1, smooth=0, scale=‘linear’)

```
Creates training points and sets up surrogate models for driving force calculations
Parameters
----------
comps : array of floats
Range of compositions for training points
temperature : float or array
Temperature or range of temperatures for training points
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
scale : float
Whether the composition training data should be in log or linear scale
Note: 'log' is recommended for dilute solutions
```

kawin.BinarySurrogate._createDGSurrogate(self)

kawin.BinarySurrogate.changeDrivingForceHyperparameters(self, function = ‘linear’, epsilon = 1, smooth = 0)

```
Re-create surrogate model for driving force with updated hyperparameters
Parameters
----------
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
```

kawin.BinarySurrogate.getDrivingForce(self, x, T, returnComp = False)

```
Gets driving force from surrogate models
Parameters
----------
x : float or array of floats
Composition
T : float or array of floats
Temperature, must be same length as x
returnComp : bool (optional)
Returns precipitate composition if True (defaults to False)
Returns
-------
(driving force, precipitate composition)
Both will be same shape as x and T
Positive driving force means that precipitate will form
precipitate composition will be None if returnComp is False
```

kawin.BinarySurrogate.trainInterfacialComposition(self, temperature, freeEnergy, function=‘linear’, epsilon=1, smooth=0, scale = ‘linear’)

```
Creates training points and sets up surrogate models for interfacial composition
Parameters
----------
temperature : float or array
Temperature or range of temperatures for training points
freeEnergy : array of floats
range of free energy values from Gibbs-Thomson contribution
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
scale : float
Whether the matrix composition output should be in log or linear scale
Note: 'log' is recommended for dilute solutions
```

kawin.BinarySurrogate.trainInterfacialCompositionFromDrivingForceData(self, function=‘linear’, epsilon=1, smooth=0, scale=‘linear’)

```
Converts driving force data ([x, T] -> G) to interfacial composition data ([T, G] -> x)
This may lead to inaccuracies in the precipitate composition since driving force calculations are done by sampling the free energy curve
Parameters
----------
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
scale : float
Whether the matrix composition output should be in log or linear scale
Note: 'log' is recommended for dilute solutions
```

kawin.BinarySurrogate._buildInterfacialCompositionModels(self, temperature, freeEnergy, function, epsilon, smooth, scale)

```
Builds interfacial composition model (this is separate to allow for both training from new data or driving force data)
Parameters
----------
temperature - range of temperatures
freeEnergy - range of free energies
function - radial basis function
epsilon - scale factor
smooth - smoothing factor
scale - linear or log scale
```

kawin.BinarySurrogate._createICSurrogate(self)

kawin.BinarySurrogate.changeInterfacialCompositionHyperparameters(self, function = ‘linear’, epsilon = 1, smooth = 0)

```
Re-create surrogate model for interfacial composition with updated hyperparameters
Parameters
----------
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
```

kawin.BinarySurrogate.getInterfacialComposition(self, T, gExtra = 0)

```
Gets Interfacial composition from surrogate models
Parameters
----------
T : float or array of floats
Temperature
gExtra : float or array of floats
Free energy from Gibbs-Thomson contribution (must be same length as T)
Returns
-------
(composition of parent phase, composition of precipitate phase)
Composition will be in same shape as T and gExtra
Will return (None, None) if gExtra is large enough that
precipitate becomes unstable
```

kawin.BinarySurrogate.trainInterdiffusivity(self, comps, temperature, function=‘linear’, epsilon=1, smooth=0, scale=‘linear’)

```
Trains interdiffusivity from mobility parameters
Parameters
----------
comps : array of floats
Range of compositions for training points
temperature : float or array
Temperature or range of temperatures for training points
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
scale : float
Whether the diffusivity output should be in log or linear scale
```

kawin.BinarySurrogate._createDiffSurrogate(self)

kawin.BinarySurrogate.changeDiffusivityHyperparameters(self, function = ‘linear’, epsilon = 1, smooth = 0)

```
Re-create surrogate model for diffusivity with updated hyperparameters
Parameters
----------
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
```

kawin.BinarySurrogate.getInterdiffusivity(self, x, T)

```
Returns interdiffusivity
Parameters
----------
x : float or array of floats
Composition
T : float or array of floats
Temperature (must be same length as x)
Returns
-------
diffusivity (same shape as x and T)
```

kawin.BinarySurrogate.drivingForceTrainingTemperature(self)

```
Returns the temperature coordinates of driving force training points
```

kawin.BinarySurrogate.drivingForceTrainingComposition(self)

```
Returns the composition coordinates of driving force training points
```

kawin.BinarySurrogate.interfacialCompositionTrainingTemperature(self)

```
Returns the temperature coordinates of interfacial composition training points
```

kawin.BinarySurrogate.interfacialCompositionTrainingGibbsThomson(self)

```
Returns the Gibbs-Thomson contribution coordinates of interfacial composition training points
```

kawin.BinarySurrogate.save(self, fileName)

```
Pickles surrogate data
Note: this will remove the user-defined driving force and interfacial compositions
This is not a problem; however, a loaded surrogate will not be
able to be re-trained with different training points
Parameters
----------
fileName : str
```

kawin.BinarySurrogate.load(fileName)

```
Loads data from a pickled surrogate and builds driving force and interfacial composition functions
Parameters
----------
fileName : str
Returns
-------
BinarySurrogate object
```

**class** kawin.MulticomponentSurrogate(self, thermodynamics = None, drivingForce = None, interfacialComposition = None, curvature = None, precPhase = None)

```
Handles surrogate models for driving force, interfacial composition
and growth rate in a multicomponent system
Parameters
----------
thermodynamics - MulticomponentThermodynamics (optional)
Driving force, interfacial composition and
curvature functions will be taken from this
If None, then drivingForce and curvature will need to be defined
drivingForce - function (optional))
Function will take in (composition, temperature) and return driving force
where a positive value means that precipitation is favorable
composition is an array for each element, excluding the reference element
interfacialComposition - function (optional)
Takes in (composition, temperature, gExtra) and returns matrix and precipitate composition
composition is an array for each element, excluding the reference element
Function should return (None, None) if precipitate is unstable
curvature - function (optional)
Function will take in (composition, temperature) and return the following:
{D-1 dCbar / dCbar^T M-1 dCbar} - for calculating interfacial composition of matrix
{1 / dCbar^T M-1 dCbar} - for calculating growth rate
{Gb^-1 Ga} - for calculating precipitate composition
Ca - interfacial composition of matrix phase
Cb - interfacial composition of precipitate phase
Function will return (None, None, None, None, None) if composition is outside two phase region
precPhase : str (optional)
Precipitate phase to consider if binaryThermodynamics is defined
Note: if binaryThermodynamics is not defined, then drivingForce and
interfacial composition needs to be defined
```

kawin.MulticomponentSurrogate.trainDrivingForce(self, comps, temperature, function=‘linear’, epsilon=1, smooth=0, scale=‘linear’)

```
Creates training points and sets up surrogate models for driving force calculations
Parameters
----------
comps : 2-D array
Range of compositions for training points
0th axis represents an individual training point
1st axis represents element composition
temperature : float or array
Range of temperatures for training points
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
scale : float
Whether the composition training data should be in log or linear scale
Note: 'log' is recommended for dilute solutions
```

kawin.MulticomponentSurrogate._createDGSurrogate(self)

kawin.MulticomponentSurrogate.changeDrivingForceHyperparameters(self, function = ‘linear’, epsilon = 1, smooth = 0)

```
Re-create surrogate model for driving force with updated hyperparameters
Parameters
----------
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
```

kawin.MulticomponentSurrogate.getDrivingForce(self, x, T, returnComp = False)

```
Gets driving force from surrogate models
Parameters
----------
x : array or 2D array
Composition (array of float for each minor element)
2D arrays will have 0th axis for each set and 1st axis for composition
T : float or array
Temperature (must be float or same length as 0th axis of x if array)
Returns
-------
driving force (positive value means that precipitate is stable)
```

kawin.MulticomponentSurrogate.trainCurvature(self, comps, temperature, function=‘linear’, epsilon=1, smooth=0, scale=‘linear’)

```
Trains for curvature factor (from Phillipes and Voorhees - 2013) as a function of composition and temperature
Creates 5 surrogates
{D-1 dCbar / dCbar^T M-1 dCbar} - for calculating interfacial composition of matrix
{1 / dCbar^T M-1 dCbar} - for calculating growth rate
{Gb^-1 Ga} - for calculating precipitate composition
Ca - interfacial composition of matrix phase
Cb - interfacial composition of precipitate phase
Parameters
----------
comps : 2D array of floats
Range of compositions for training points
0th axis represents a training point
1st axis represents element compositions
temperature : float or array
Range of temperatures for training points
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
scale : float
Whether the matrix composition output should be in log or linear scale
Note: 'log' is recommended for dilute solutions
```

kawin.MulticomponentSurrogate._createICSurrogate(self)

kawin.MulticomponentSurrogate.changeCurvatureHyperparameters(self, function = ‘linear’, epsilon = 1, smooth = 0)

```
Re-create surrogate model for curvature factors with updated hyperparameters
Parameters
----------
function : str (optional)
Radial basis function to use (defaults to 'linear')
Other functions are 'multiquadric', 'inverse_multiquadric',
'gaussian', 'cubic', 'quintic' and 'thin_plate'
epsilon : float
Scale for radial basis function (defaults to 1)
Training data will be scaled automatically
such that optimal scale is around 1
smooth : float
Smoothness of interpolation, (defaults to 0, where interpolation will go through all points)
scale : float
Whether the composition training data should be in log or linear scale
Note: 'log' is recommended for dilute solutions
```

kawin.MulticomponentSurrogate.getCurvature(self, x, T)

```
Gets driving force from surrogate models
Parameters
----------
x : array or 2D array
Composition (array of float for each minor element)
2D arrays will have 0th axis for each set and 1st axis for composition
T : float or array
Temperature (must be float or same length as 0th axis of x if array)
Returns
-------
Curvature factors
{D-1 dCbar / dCbar^T M-1 dCbar} - for calculating interfacial composition of matrix
{1 / dCbar^T M-1 dCbar} - for calculating growth rate
{Gb^-1 Ga} - for calculating precipitate composition
Ca - interfacial composition of matrix phase
Cb - interfacial composition of precipitate phase
Note: this function currently does not return (None, None, None, None, None)
if precipitate is unstable
```

kawin.MulticomponentSurrogate.getGrowthAndInterfacialComposition(self, x, T, dG, R, gExtra)

```
Returns growth rate and interfacial compostion given Gibbs-Thomson contribution
Parameters
----------
x : array of floats
Matrix composition
T : float
Temperature
dG : float
Driving force
R : float or array
Precipitate radius
gExtra : float or array
Gibbs-Thomson contribution corresponding to R
Must be same shape as R
Returns
-------
(growth rate, matrix composition, precipitate composition)
Growth rate will be float or array depending on R
matrix and precipitate composition will be 1D or 2D array depending on R
1D array will be length of composition
2D array will have 0th axis be length of R and 1st axis be length of composition
```

kawin.MulticomponentSurrogate.impingementFactor(self, x, T)

```
Calculates impingement factor for nucleation rate calculations
Parameters
----------
x : array of floats
Matrix composition
T : float
Temperature
```

kawin.MulticomponentSurrogate.save(self, fileName)

```
Pickles surrogate data
Note: this will remove the user-defined driving force and curvature functions
This is not a problem; however, a loaded surrogate will not be
able to be re-trained with different training points
Parameters
----------
fileName : str
```

kawin.MulticomponentSurrogate.load(fileName)

```
Loads data from a pickled surrogate and builds driving force and curvature functions
Parameters
----------
fileName : str
Returns
-------
MulticomponentSurrogate object
```