Note
This module is a work in progress and will be gradually updated.
pyrolite.mineral.template
- class pyrolite.mineral.template.MineralTemplate(name, *components)[source]
- class pyrolite.mineral.template.Mineral(name=None, template=None, composition=None, endmembers=None)[source]
- set_composition(composition=None)[source]
Parse and assign a composition to the mineral.
- Parameters:
composition – Composition to assign to the mineral. Can be provided in any form which is digestable by parse_composition.
- recalculate_cations(composition=None, ideal_cations=None, ideal_oxygens=None, Fe_species=['FeO', 'Fe', 'Fe2O3'], oxygen_constrained=False)[source]
Recalculate a composition to give an elemental ionic breakdown.
- Parameters:
composition – Composition to recalculate. If not provided, will try to use the mineral composition as set.
ideal_cations (int) – Ideal number of cations to use for formulae calcuations. Will only be used if oxygen is constrained (i.e. multiple Fe species present or oxygen_constrained=True).
ideal_oxygens (int) – Ideal number of oxygens to use for formulae calcuations. Will only be used if oxygen is not constrained (i.e. single Fe species present and oxygen_constrained=False).
Fe_species (list) – List of iron species for identifying redox-defined compositions.
oxygen_constrained (bool, False) – Whether the oxygen is a closed or open system for the specific composition.
- endmember_decompose(det_lim=0.01)[source]
Decompose a mineral composition into endmember components.
- Parameters:
det_lim (float) – Detection limit for individual
Notes
Currently implmented using optimization based on mass fractions.
Todo
Implement site-based endmember decomposition, which will enable more checks and balances.
- calculate_occupancy(composition=None, error=1e-05, balances=[['Fe{2+}', 'Mg{2+}']])[source]
Calculate the estimated site occupancy for a given composition. Ions will be assigned to sites according to affinities. Sites with equal affinities should recieve equal assignment.
- Parameters:
composition – Composition to calculate site occupancy for.
error (float) – Absolute error for floating point occupancy calculations.
balances (list) – List of iterables containing ions to balance across multiple sites. Note that the partitioning will occur after non-balanced cations are assigned, and that ions are only balanced between sites which have defined affinities for all of the particular ions defined in the ‘balance’.
pyrolite.mineral.normative
- pyrolite.mineral.normative.unmix(comp, parts, order=1, det_lim=0.0001)[source]
From a composition and endmember components, find a set of weights which best approximate the composition as a weighted sum of components.
- Parameters:
comp (
numpy.ndarray) – Array of compositions (shape \(n_S, n_C\)).parts (
numpy.ndarray) – Array of endmembers (shape \(n_E, n_C\)).order (
int) – Order of regularization, defaults to L1 for sparsity.det_lim (
float) – Detection limit, below which minor components will be omitted for sparsity.- Returns:
Array of endmember modal abundances (shape \(n_S, n_E\))
- Return type:
- pyrolite.mineral.normative.endmember_decompose(composition, endmembers=[], drop_zeros=True, molecular=True, order=1, det_lim=0.0001)[source]
Decompose a given mineral composition to given endmembers.
- Parameters:
composition (
DataFrame|Series|Formula|str) – Composition to decompose into endmember components.endmembers (
str|list|dict) – List of endmembers to use for the decomposition.drop_zeros (
bool,True) – Whether to omit components with zero estimated abundance.molecular (
bool,True) – Whether to convert the chemistry to molecular before calculating the decomposition.order (
int) – Order of regularization passed tounmix(), defaults to L1 for sparsity.det_lim (
float) – Detection limit, below which minor components will be omitted for sparsity.- Return type:
- pyrolite.mineral.normative.MiddlemostOxRatio(df)[source]
Apply a TAS classification to a dataframe, and get estimated Fe2O3/FeO ratios from Middlemost (1989).
- Parameters:
df (
pandas.DataFrame) – Dataframe to get Fe2O3/FeO ratios for, containing the required oxides to calculate TAS diagrams from (i.e. SiO2, Na2O, K2O).- Returns:
ratios – Series of estimated Fe2O3/FeO ratios, based on TAS classification.
- Return type:
References
Middlemost, Eric A. K. (1989). Iron Oxidation Ratios, Norms and the Classification of Volcanic Rocks. Chemical Geology 77, 1: 19–26. https://doi.org/10.1016/0009-2541(89)90011-9.
- pyrolite.mineral.normative.LeMaitreOxRatio(df, mode=None)[source]
- Parameters:
df (
pandas.DataFrame) – Dataframe containing compositions to calibrate against.mode (
str) – Mode for the correction - ‘volcanic’ or ‘plutonic’.- Returns:
Series with oxidation ratios.
- Return type:
Notes
This is a \(\mathrm{FeO / (FeO + Fe_2O_3)}\) mass ratio, not a standard molar ratio \(\mathrm{Fe^{2+}/(Fe^{2+} + Fe^{3+})}\) which is more straightfowardly used; data presented should be in mass units. For the calculation, SiO2, Na2O and K2O are expected to be present.
References
Le Maitre, R. W (1976). Some Problems of the Projection of Chemical Data into Mineralogical Classifications. Contributions to Mineralogy and Petrology 56, no. 2 (1 January 1976): 181–89. https://doi.org/10.1007/BF00399603.
- pyrolite.mineral.normative.Middlemost_Fe_correction(df)[source]
- Parameters:
df (
pandas.DataFrame) – Dataframe containing compositions to calibrate against.- Returns:
Series with two corrected iron components (\(\mathrm{FeO, Fe_2O_3}\)).
- Return type:
References
Middlemost, Eric A. K. (1989). Iron Oxidation Ratios, Norms and the Classification of Volcanic Rocks. Chemical Geology 77, 1: 19–26. https://doi.org/10.1016/0009-2541(89)90011-9.
- pyrolite.mineral.normative.LeMaitre_Fe_correction(df, mode='volcanic')[source]
- Parameters:
df (
pandas.DataFrame) – Dataframe containing compositions to correct iron for.mode (
str) – Mode for the correction - ‘volcanic’ or ‘plutonic’.- Returns:
Series with two corrected iron components (\(\mathrm{FeO, Fe_2O_3}\)).
- Return type:
References
Le Maitre, R. W (1976). Some Problems of the Projection of Chemical Data into Mineralogical Classifications. Contributions to Mineralogy and Petrology 56, no. 2 (1 January 1976): 181–89. https://doi.org/10.1007/BF00399603.
Middlemost, Eric A. K. (1989). Iron Oxidation Ratios, Norms and the Classification of Volcanic Rocks. Chemical Geology 77, 1: 19–26. https://doi.org/10.1016/0009-2541(89)90011-9.
- pyrolite.mineral.normative.CIPW_norm(df, Fe_correction=None, Fe_correction_mode=None, adjust_all_Fe=False, return_adjusted_input=False, return_free_components=False, rounding=3)[source]
Standardised calcuation of estimated mineralogy from bulk rock chemistry. Takes a dataframe of chemistry & creates a dataframe of estimated mineralogy. This is the CIPW norm of Verma et al. (2003). This version only uses major elements.
- Parameters:
df (
pandas.DataFrame) – Dataframe containing compositions to transform.Fe_correction (
str) – Iron correction to apply, if any. Will default to ‘LeMaitre’.Fe_correction_mode (
str) – Mode for the iron correction, where applicable.adjust_all_Fe (
bool) – Where correcting iron compositions, whether to adjust all iron compositions, or only those where singular components are specified.return_adjusted_input (
bool) – Whether to return the adjusted input chemistry with the output.return_free_components (
bool) – Whether to return the free components in the output.rounding (
int) – Rounding to be applied to input and output data.- Return type:
References
Verma, Surendra P., Ignacio S. Torres-Alvarado, and Fernando Velasco-Tapia (2003). A Revised CIPW Norm. Swiss Bulletin of Mineralogy and Petrology 83, 2: 197–216. Verma, S. P., & Rivera-Gomez, M. A. (2013). Computer Programs for the Classification and Nomenclature of Igneous Rocks. Episodes, 36(2), 115–124.
Todo
Note whether data needs to be normalised to 1 or 100?
Notes
The function expect oxide components to be in wt% and elemental data to be in ppm.
pyrolite.mineral.transform
- pyrolite.mineral.transform.formula_to_elemental(formula, weight=True)[source]
Convert a periodictable.formulas.Formula to elemental composition.
pyrolite.mineral.sites
- class pyrolite.mineral.sites.MX(name='M', coordination=8, *args, **kwargs)[source]
Octahedrally coordinated M site.
- class pyrolite.mineral.sites.TX(name='T', coordination=4, affinities={'Al{3+}': 1, 'Fe{3+}': 2, 'Si{4+}': 0}, *args, mode='cation', **kwargs)[source]
Tetrahedrally coordinated T site.
- class pyrolite.mineral.sites.IX(name='I', coordination=12, *args, **kwargs)[source]
Dodecahedrally coordinated I site.
pyrolite.mineral.lattice
Submodule for calcuating relative ion paritioning based on the lattice strain model [1] [2] [3].
References
- pyrolite.mineral.lattice.strain_coefficient(ri, rx, r0=None, E=None, T=298.15, z=None, **kwargs)[source]
Calculate the lattice strain associated with an ionic substitution [6] [7].
- Parameters:
ri (
float) – Ionic radius to calculate strain relative to, in angstroms (Å).rj (
float) – Ionic radius to calculate strain for, in angstroms (Å).r0 (
float,None) – Fictive ideal ionic radii for the site. The value forriwill be used in its place if none is given, and a warning issued.E (
float,None) – Young’s modulus (stiffness) for the site, in pascals (Pa). Will be estimated usingyoungs_modulus_approximation()if none is given.T (
float) – Temperature, in Kelvin (K).z (
int) – Optional specification of cationic valence, for calcuation of approximate Young’s modulus usingyoungs_modulus_approximation(), where the modulus is not specified.- Returns:
The strain coefficent \(e^{\frac{-\Delta G_{strain}}{RT}}\).
- Return type:
Notes
The lattice strain model relates changes in paritioning to differences in ionic radii for ions of a given cationic charge, and for a for a specific site (with Young’s modulus \(E\)). This is calcuated using the work done to expand a spherical shell centred on the lattice site, which alters the \(\Delta G\) for the formation of the mineral. This can be related to changes in partition coefficients using the following [7]:
\[D_{j^{n+}} = D_{A^{n+}} \cdot e^{\frac{-4\pi E N \Big(\frac{r_{0}}{2}(r_j - r_0)^2 + \frac{1}{3}(r_j - r_0)^3\Big)}{RT}}\]Where \(D_{A^{n+}}\) is the partition coefficient for the ideal ion A, and N is Avagadro’s number (6.023e23 atoms/mol). This can also be calcuated relative to an ‘ideal’ fictive ion which has a maximum \(D\) where this data are available. This relationship arises via i) the integration to calcuate the strain energy mentioned above (\(4\pi E (\frac{r_{0}}{2}(r_j - r_0)^2 + \frac{1}{3}(r_j - r_0)^3)\)), and ii) the assumption that the changes in \(\Delta G\) occur only to size differences, and the difference is additive. The ‘segregation coefficient’ \(K_j\) can be expressed relative to the non-doped equilibirum constant \(K_0\) [6]:
\[\begin{split}\begin{align} K_j &= e^{\frac{-\Delta G_0 -\Delta G_{strain}}{RT}}\\ &= e^{\frac{-\Delta G_0}{RT}} \cdot e^{\frac{-\Delta G_{strain}}{RT}}\\ &= K_0 \cdot e^{\frac{-\Delta G_{strain}}{RT}}\\ \end{align}\end{split}\]The model assumes that the crystal is elastically isotropic.
References
- pyrolite.mineral.lattice.youngs_modulus_approximation(z, r)[source]
Young’s modulus approximation for cationic sites in silicates and oxides [8] [9] [10].
- Parameters:
z (
integer) – Cationic valence.r (
float) – Ionic radius of the cation (Å).- Returns:
E – Young’s modulus for the cationic site, in Pascals (Pa)
- Return type:
Notes
The bulk modulus \(K\) for an an ionic crystal is esimated using [8]:
\[K = \frac{A Z_a Z_c e^2 (n-1)}{9 d_0 V_0}\]Where \(A\) is the Madelung constant, \(Z_c\) and \(Z_a\) are the anion and cation valences, \(e\) is the charge on the electron, \(n\) is the Born power law coefficent, and \(d_0\) is the cation-anion distance [8]. Using the Shannon ionic radius for oxygen (1.38 Å), this is approximated for cations coordinated by oxygen in silicates and oxides using the following relationship [9]:
\[K = 750 Z_c d^{-3}\]Where \(d\) is the cation-anion distance (Å), \(Z_c\) is the cationic valence (and \(K\) is in GPa). The Young’s modulus \(E\) is then calculated through the relationship [10]:
\[E = 3 K (1 - 2 \sigma)\]Where \(\sigma\) is Poisson’s ratio, which in the case of minerals can be approimxated by 0.25 [10], and hence:
\[\begin{split}\begin{align} E &\approx 1.5 K\\ E &\approx 1025 Z_c d^{-3} \end{align}\end{split}\]Todo
Add links to docstring
References
- pyrolite.mineral.lattice.fit_lattice_strain(radii, ys, E=None, z=3, bounds=[(0.1, 2.2), (273.15, 2973.15), (0, inf)], r0=None, t0=773.15, d0=1.0, **kwargs)[source]
Fit a lattice strain model to a given set of abundances.
- Parameters:
radii (
numpy.ndarray) – Radii to fit against.ys (
numpy.ndarray) – Partition coefficients for given elemental data.E (
float,None) – Young’s modulus (stiffness) for the site, in pascals (Pa). Will be estimated usingyoungs_modulus_approximation()if none is given.z (
int) – Optional specification of cationic valence, for calcuation of approximate Young’s modulus usingyoungs_modulus_approximation(), where the modulus is not specified.bounds (
list) – List of tuples specifying bounds on parameters ri, T and D.- Returns:
ri, tk, D – Radius, temperature and partition coefficeint describing the lattice strain fit.
- Return type:
Notes
Uses the youngs modulus approximation where E not provided.
Passes keyword arguments to
scipy.optimize_curve_fit().
pyrolite.mineral.mindb
Submodule for accessing the rock forming mineral database.
Notes
Accessing and modifying the database across multiple with multiple threads/processes could result in database corruption (e.g. through repeated truncation etc).
- pyrolite.mineral.mindb.list_groups()[source]
List the mineral groups present in the mineral database.
- Return type:
- pyrolite.mineral.mindb.list_minerals()[source]
List the minerals present in the mineral database.
- Return type:
- pyrolite.mineral.mindb.list_formulae()[source]
List the mineral formulae present in the mineral database.
- Return type:
- pyrolite.mineral.mindb.get_mineral(name='', dbpath=None)[source]
Get a specific mineral from the database.
- Parameters:
name (
str) – Name of the desired mineral.dbpath (
pathlib.Path,str) – Optional overriding of the default database path.- Return type:
pd.Series
- pyrolite.mineral.mindb.parse_composition(composition, drop_zeros=True)[source]
Parse a composition reference to provide an ionic elemental version in the form of a
Series. Currently acceptspandas.Series,periodictable.formulas.Formulaand structures which will directly convert topandas.Series(list of tuples, dict).
- Parameters:
composition (
str|periodictable.formulas.Formula|pandas.Series) – Name of a mineral, a formula or composition as a seriesdrop_zeros (
bool) – Whether to drop compositional zeros.- Returns:
mineral – Composition formatted as a series.
- Return type:
- pyrolite.mineral.mindb.get_mineral_group(group='')[source]
Extract a mineral group from the database.
- Parameters:
group (
str) – Group to extract from the mineral database.- Returns:
Dataframe of group members and compositions.
- Return type:
- pyrolite.mineral.mindb.update_database(path=None, **kwargs)[source]
Update the mineral composition database.
- Parameters:
path (
str|pathlib.Path) – The desired filepath for the JSON database.Notes
This will take the ‘mins.csv’ file from the mineral pyrolite data folder and construct a document-based JSON database.