macchiato api

Module contents

Data-driven nearest neighbor models for predicting experimental results on silicon lithium-ion battery anodes.

modules

macchiato.experiments

Module with the physical experiments to fit and predict.

macchiato.experiments.nmr

Prediction of 7Li NMR chemical shift spectra.

class macchiato.experiments.nmr.ChemicalShiftCenters(universe, start=None, stop=None, step=None)

Bases: NearestNeighbors

Obtain the peak centers of each Li atom.

The nearest-neighbor model consist of considering that each Li atom makes a particular contribution to the total chemical shift spectra. The ansatz chosen to locate the center of the peak was inspired by a comment from Ket et al. [1], who stated that if a Li atom is near a bonded Si, then the center of its peak is at 18ppm, whereas if it is near an isolated Si atom, the center should be at 6ppm. To take into account intermediate contributions that appears in the spectra we define the peak position of each Li atom as follow,

\(\delta_{Li} = \frac{1}{N_{Si}} \sum_{Si \in NN} \delta_{Key}\),

where the sum is considered over all first nearest-neighbors (NN) Si atoms (\(N_{Si}\)) and \(\delta_{Key}\) is the shift value of 18ppm or 6ppm depending of the Si type.

Parameters:

universe (MDAnalysis.core.universe.Universe) – a MDAnalysis Universe with the box defined
start (int, default=None) – start frame of analysis
stop (int, default=None) – stop frame of analysis
step (int, default=None) – number of frames to skip between each analyzed one

References

bonded_

the percentage of bonded Si atoms

Type:: float

isolated_

the percentage of isolated Si atoms

Type:: float

contributions_

the mean of the peak in the chemical shift spectra per Li atom

Type:: numpy.ndarray

fit(X, y=None, sample_weight=None)

Fit method.

Parameters:

X (ignored) – not used here, just convention, it uses the snapshots in the trajectory
y (ignored) – not used, just convention

Returns:

self – fitted model

Return type:

object

fit_predict(X, y=None, sample_weight=None)

Compute the clustering and predict the Li chemical shift centers.

Parameters:

X (ignored) – not used here, just convention, it uses the snapshots in the trajectory
y (ignored) – not used, just convention

Returns:

contributions_ – the mean of the peak in the chemical shift spectra per Li atom

Return type:

numpy.ndarray

class macchiato.experiments.nmr.ChemicalShiftWidth(csc)

Bases: RegressorMixin

Fit the overall width of a Li chemical shift spectra given the centers.

A Voigt contribution is assumed for each center with the same width and same heigth and the total intensity is a sum of them.

Parameters:: csc (macchiato.chemical_shift.ChemicalShiftCenters or numpy.ndarray) – a ChemicalShiftCenters object already fitted or a numpy array with the centers

sigma_

the fitted standard deviation of the gaussian component of each voigt peak

Type:: float

gamma_

the fitted half-width at half-maximum of the lorentzian component of each voigt peak

Type:: float

heigth_

the fitted heigth of each voigt peak

Type:: float

fit(X, y)

Fit the width of the Li NMR profile to the experimental data.

Parameters:

X (array-like of shape (n_ppm, 1)) – chemical shift ppm points
y (array-like of shape (n_ppm,)) – target intensity

Returns:

self – fitted peaks

Return type:

object

predict(X)

Predict the Li chemical shift spectra.

Parameters:: X (array-like of shape (n_ppm, 1)) – chemical shift ppm points
Returns:: y – predicted intensity
Return type:: array-like of shape (n_ppm,)

score(X, y)

Return the coefficient of determination of the prediction.

Parameters:

X (array-like of shape (n_ppm, 1)) – chemical shift ppm points
y (array-like of shape (n_ppm,)) – true intensity

Returns:

score – \(R^2\) of self.predict(X) wrt. y.

Return type:

float

class macchiato.experiments.nmr.ChemicalShiftSpectra(csc, csw)

Bases: object

Plot the Li chemical shift spectra once you have the centers and width.

Parameters:

csc (macchiato.chemical_shift.ChemicalShiftCenters or numpy.ndarray) – a ChemicalShiftCenters object already fitted or a numpy array with the centers
csw (macchiato.chemical_shift.ChemicalShiftWidth or numpy.ndarray) – a ChemicalShiftWidth object already fitted or numpy.ndarray with sigma, gamma and heigth params of each voigt peak per Li atom

property plot: Plot accesor to macchiato.plot SpectraPlotter.

macchiato.experiments.mossbauer

Prediction Mössbauer 119Sn (equiv. Si atoms) spectra peaks splitting.

class macchiato.experiments.mossbauer.MossbauerEffect(universe, start=None, stop=None, step=None)

Bases: NearestNeighbors

Delta of a splitting in a two-contribution peak in Mössbauer spectra.

We define a \(z\)-value as the minimum between Li and Si concentrations in the first coordination shell of each Si atom, i.e., \(0 \leq z \leq 0.5\). Then, there is a linear relationship between \(\Delta\) of each Si atom with its \(z\)-value. This was inspired by Li et al. work [2].

Parameters:

universe (MDAnalysis.core.universe.Universe) – a MDAnalysis Universe with the box defined
start (int, default=None) – start frame of analysis
stop (int, default=None) – stop frame of analysis
step (int, default=None) – number of frames to skip between each analyzed one

References

contributions_

the mean of the Mössbauer effect delta between spectra peaks per Si atom

Type:: numpy.ndarray

fit(X, y=None, sample_weight=None)

Fit method.

Parameters:

X (ignored) – not used here, just convention, it uses the snapshots in the trajectory
y (ignored) – not used, just convention

Returns:

self – fitted model

Return type:

object

fit_predict(X, y=None, sample_weight=None)

Compute the clustering and predict the delta splitting.

To obtain each \(\Delta\) an average is perfomed in the trajectory of the Si atom.

Parameters:

X (ignored) – not used here, just convention, it uses the snapshots in the trajectory
y (ignored) – not used, just convention

Returns:

contributions_ – the mean of the Mössbauer effect delta between spectra peaks per Si atom

Return type:

numpy.ndarray

macchiato.experiments.xray

Predictions of PDF by fitting experiments to the structures.

class macchiato.experiments.xray.PairDistributionFunction(universes)

Bases: object

X-ray Pair Distribution Function (PDF or \(G(r)\)).

PDF can be computed from Radial Distribution Function (RDF) by considering the contribution of each interaccion (Si-Si, Si-Li, Si-Si) given its scattering factor. Then, a measurement that has a mixture of alloys can be fitted to determine the weight factor of each one to predict the experiment.

Parameters:: universes (list of MDAnalysis.core.universe.Universe) – a list of universes with the box defined per alloy to be considered

weights_

weight of each alloy in the same order as in the list of universes

Type:: numpy.ndarray

offset_

y-axis offset

Type:: float

rbins_

rvalues corresponding to the gofr y-values

Type:: numpy.ndarray

gofrs_

a list with the PDF of each alloy in the same order as the list of universes

Type:: list of numpy.ndarray

fit(X, y)

Fit the weights of each alloy.

Parameters:

X (array-like of shape (rvalues, 1)) – r values
y (array-like of shape (rvalues,)) – target intensity of the total PDF

Returns:

self – fitted weights

Return type:

object

predict(X)

Predict the X-ray PDF.

Parameters:: X (array-like of shape (rvalues, 1)) – rvalues
Returns:: y – predicted intensity of the total PDF
Return type:: array-like of shape (rvalues,)

property plot: Plot accesor to macchiato.plot PDFPlotter.

macchiato.plot

Plotter class.

class macchiato.plot.SpectraPlotter(css)

Bases: object

Chemical shift plotter.

Kind of plots to produce:

‘predicted’ : the predicted spectra
‘versus_data’ : the predicted versus true spectra

Parameters:: css (macchiato.experiments.nmr.ChemicalShiftSpectra) – an already fitted chemical shift spectra

predicted(X, ax=None, **kwargs)

Plot the predicted spectra.

Parameters:

X (array-like of shape (n_ppm, 1)) – chemical shift ppm points to evaluate the spectra
ax (matplotlib.axes.Axes, default=None) – the current axes
**kwargs – additional keyword arguments that are passed and are documented in matplotlib.axes.Axes.plot for the predictions values.

Returns:

ax – the current axes

Return type:

matplotlib.axes.Axes

versus_data(X, y, ax=None, true_kws=None, pred_kws=None)

Plot the predicted spectra against the true data.

Parameters:

X (array-like of shape (n_ppm, 1)) – chemical shift ppm points
y (array-like of shape (n_ppm,)) – true intensity
ax (matplotlib.axes.Axes, default=None) – the current axes
true_kws (dict, default=None) – additional keyword arguments that are passed and are documented in matplotlib.axes.Axes.scatter for the true values.
pred_kws (dict, default=None) – additional keyword arguments that are passed and are documented in matplotlib.axes.Axes.plot for the predictions values.

Returns:

ax – the current axes

Return type:

matplotlib.axes.Axes

class macchiato.plot.PDFPlotter(pdf)

Bases: object

X-ray PDF plotter.

Produce a plot with the predicted versus the true PDF.

Parameters:: pdf (macchiato.experiments.xray.PairDistributionFunction) –

versus_data(X, y, ax=None, true_kws=None, pred_kws=None)

Plot the predicted PDF against the true data.

Parameters:

X (array-like of shape (rvalues, 1)) – r values
y (array-like of shape (rvalues,)) – target intensity of the total PDF
ax (matplotlib.axes.Axes, default=None) – the current axes
true_kws (dict, default=None) – additional keyword arguments that are passed and are documented in matplotlib.axes.Axes.scatter for the true values.
pred_kws (dict, default=None) – additional keyword arguments that are passed and are documented in matplotlib.axes.Axes.plot for the predictions values.

Returns:

ax – the current axes

Return type:

matplotlib.axes.Axes

macchiato.utils

NMR profile peaks.

macchiato.utils.voigt_peak(x, mean, sigma, gamma, heigth=1.0)

Voigt profile.

Parameters:

x (np.ndarray) – x values to evaluate the voigt peak
mean (float) – expected value or mean
sigma (float) – the standard deviation of the gaussian component
gamma (float) – the half-width at half-maximum of the lorentzian component
heigth (float, default=1.0) – optional heigth of the peak

Returns:

evaluation of the voigt peak in the x values given the parameters

Return type:

np.ndarray

macchiato.utils.nmr_profile(X, centers, sigma, gamma, heigth=1.0)

NMR profile with a voigt contribution per center.

Parameters:

X (np.ndarray) – X values to evaluate the voigt peak
centers (np.ndarray) – array with expected value or mean per center
sigma (float) – the standard deviation of the gaussian component
gamma (float) – the half-width at half-maximum of the lorentzian component
heigth (float, default=1.0) – optional heigth of the peak

Returns:

evaluation of the voigt peak in the x values given the parameters

Return type:

np.ndarray

macchiato.base

NearestNeighbors base class.

class macchiato.base.NearestNeighbors(universe, atom_type, start=None, stop=None, step=None)

Bases: ClusterMixin, BaseEstimator

Nearest Neighbors Clustering.

Parameters:

universe (MDAnalysis.core.universe.Universe) – a MDAnalysis Universe with the box defined
atom_type (str or int) – type of atom on which to analyze the proximity to the clusters
start (int, default=None) – start frame of analysis
stop (int, default=None) – stop frame of analysis
step (int, default=None) – number of frames to skip between each analyzed one

contributions_

the contribution of the atom_type atoms

Type:: np.array

fit(X, y=None, sample_weight=None)

Fit method.

Parameters:

X (ignored) – not used here, just convention, it uses the snapshots in the trajectory
y (ignored) – not used, just convention

Returns:

self – fitted model

Return type:

object

fit_predict(X, y=None, sample_weight=None)

Compute the clustering and predict the contributions.

Parameters:

X (ignored) – not used here, just convention, it uses the snapshots in the xyz_fname
y (ignored) – not used, just convention

Returns:

contributions_ – the contribution of the atom_type atoms

Return type:

np.array