API Reference

Core Objects

The two primary objects in stellar_geology: stars and the planets derived from them.

Star

The Star module defines the Star class for representing stellar compositions and converting them through the dex-to-oxide pipeline.

class stellar_geology.star.Star(stellar_dex=None, wtpt_oxides=None, name=None, mass=None)

Bases: object

property stellar_dex: dict[str, float] | None

Stellar composition in dex notation.

Auto-computed in reverse from wtpt_oxides if not provided directly. See CAVEATS.md for the constant-offset ambiguity in recovered dex values.

Type:

dict[str, float] or None

property name: str | None

Star name.

Type:

str or None

property mass: float | None

Star mass (not yet used in calculations).

Type:

float or None

property ax: dict[str, float] | None

Elemental ratio relative to solar (10^dex).

Type:

dict[str, float] or None

property atoms_ref_solar: dict[str, float] | None

Number of atoms referenced to solar abundances.

Type:

dict[str, float] or None

property total_wt_atoms: dict[str, float] | None

Total weight of atoms (element wt scaled by atomic mass).

Type:

dict[str, float] or None

property wtpt_elements: dict[str, float] | None

Composition as wt% elements.

When computed forward from stellar_dex, includes volatile elements (C, O, S). When computed in reverse from wtpt_oxides, only rock-forming elements are present — volatiles are irrecoverable from oxide data.

Type:

dict[str, float] or None

property wtpt_oxides: dict[str, float] | None

Composition as wt% oxides (volatile-free).

Type:

dict[str, float] or None

get_composition(units='wtpt_oxides')

Return the star’s composition in the requested units.

Output dicts always sum to the target for the requested units — 100 for percent units (wtpt_*, molpt_*) and 1.0 for fraction units (wtfrac_*, molfrac_*). molfrac_singleO is the exception: it is never normalized.

Parameters:

units (str) – One of ‘wtpt_oxides’, ‘wtpt_elements’, ‘wtfrac_oxides’, ‘wtfrac_elements’, ‘molfrac_oxides’, ‘molfrac_elements’, ‘molfrac_singleO’, ‘molpt_oxides’, ‘molpt_elements’.

Returns:

Composition in the requested units.

Return type:

dict[str, float]

Raises:

ValueError – If units is invalid, or if no compositional data has been provided to the Star (neither stellar_dex nor wtpt_oxides), or the requested element-basis output is unavailable for a Star initialized from oxides.

Notes

Star element outputs (wtpt_elements, wtfrac_elements) include volatile elements (C, O, S) from the stellar pipeline when initialized from stellar_dex. When initialized from wtpt_oxides, volatile elements are not available — only rock-forming elements are returned.

Planet

The Planet module defines the Planet class for representing planetary bulk and silicate compositions derived from stellar data or direct geochemical inputs.

class stellar_geology.planet.Planet(bulk_planet=None, bulk_silicate_planet=None, stellar_dex=None, alphas=None, name=None, mass=None, mineralogy=None, units='wtpt_oxides')

Bases: object

property bulk_planet: dict[str, float] | None

Bulk planet composition in wt% oxides.

Auto-calculated from stellar_dex or bulk_silicate_planet + alphas if not provided directly.

Type:

dict[str, float] or None

property bulk_silicate_planet: dict[str, float] | None

Bulk silicate planet composition in wt% oxides.

Auto-calculated from bulk_planet + alphas if not provided directly.

Type:

dict[str, float] or None

property stellar_dex: dict[str, float] | None

Stellar composition in dex notation.

Auto-calculated from bulk_planet if not provided directly.

Type:

dict[str, float] or None

property alphas: dict[str, float] | None

Element partitioning ratios (BSP/BP) for core formation.

Auto-calculated from bulk_planet + bulk_silicate_planet if not provided directly.

Type:

dict[str, float] or None

property name: str | None

Planet name.

Type:

str or None

property mass: float | None

Planet mass (not yet implemented).

Type:

float or None

classmethod from_star(star, **kwargs)

Create a Planet from a Star object.

Parameters:

star (Star) – A Star instance with a stellar_dex composition.

Returns:

A new Planet initialized with the star’s dex composition.

Return type:

Planet

set_alphas(alphas)

Update the mantle-core partitioning coefficients alphas.

Parameters:

alphas (dict[str, float] or None) – Mantle-core partitioning coefficients, or None to clear.

Return type:

None

Examples

Calculate bulk silicate planet compositions across a range of alpha values:

>>> p = Planet.from_star(star, alphas={'Fe': 0.49, 'Ni': 0.49})
>>> bsps = {}
>>> for alpha_fe in (0.30, 0.40, 0.49, 0.55):
...     p.set_alphas({'Fe': alpha_fe, 'Ni': 0.49})
...     bsps[alpha_fe] = p.bulk_silicate_planet

get_composition(which, units='wtpt_oxides')

Return the planet’s composition in the requested units.

Output dicts always sum to the target for the requested units — 100 for percent units (wtpt_*, molpt_*) and 1.0 for fraction units (wtfrac_*, molfrac_*).

Parameters:

• which (str) – One of ‘bulk_planet’, ‘bulk_silicate_planet’.

• units (str) – One of ‘wtpt_oxides’, ‘wtpt_elements’, ‘wtfrac_oxides’, ‘wtfrac_elements’, ‘molfrac_oxides’, ‘molfrac_elements’, ‘molfrac_singleO’, ‘molpt_oxides’, ‘molpt_elements’.

Returns:

Composition in the requested units.

Return type:

dict[str, float]

Raises:

ValueError – If which or units is invalid, or if the requested composition cannot be computed from the inputs provided to the Planet (e.g. bulk_silicate_planet was requested but no alphas were provided).

Notes

Planet element outputs do not include volatile elements (C, O, S). We assume volatiles are mostly lost during planet formation. Element conversions go through the oxide-based converter, which only includes non-volatile rock-forming elements.

Calculations

Functions that transform compositions into derived quantities.

Mineralogy

CIPW normative mineralogy calculations.

Provides functions to compute normative mineral assemblages (olivine, clinopyroxene, orthopyroxene, garnet) from silicate compositions using the Thompson (1982) reaction-space approach as implemented in Putirka and Rarick (2019).

stellar_geology.mineralogy.calculate_mineralogy(silicate_composition, units='wtpt_oxides')

Calculates the CIPW normative mineralogy for olivine (ol), clinopyroxene (cpx), orthopyroxene (opx), and garnet (gar). Uses equations of Thompson (1982) “Reaction space: An algebraic and geometric approach” as implemented in Putirka and Rarick (2019) supplemental spreadsheet 2.

Parameters:

• silicate_composition (dict[str, float]) – Dictionary of chemical components describing a bulk silicate composition. Must include, at a minimum, keys for SiO2, Al2O3, FeO, MgO, and CaO (any units).

• units (str) – Units of the silicate_composition dict. Defaults to ‘wtpt_oxides’. Any valid unit string is accepted (e.g., ‘wtpt_elements’, ‘molfrac_oxides’). Compositions are converted to wt% oxides internally.

Returns:

Normative mineralogy with keys “olivine”, “clinopyroxene”, “orthopyroxene”, “garnet”.

Return type:

dict[str, float]

stellar_geology.mineralogy.calculate_composition_from_mineralogy(mineralogy, mg_number)

Recovers a bulk silicate planet composition (wt% oxides) from CIPW normative mineralogy. This is the partial inverse of calculate_mineralogy().

Because the forward pipeline compresses FeO + MgO into a single FmO component, an assumed Mg# is required to split FmO back into FeO and MgO.

Only the 5 CIPW oxides (SiO2, Al2O3, FeO, MgO, CaO) are recovered; minor oxides (TiO2, Na2O, Cr2O3, NiO) discarded in the forward pipeline cannot be reconstructed.

Parameters:

• mineralogy (dict[str, float]) – Dictionary with keys “olivine”, “clinopyroxene”, “orthopyroxene”, “garnet” and float values (mol fractions, as returned by calculate_mineralogy).

• mg_number (float) – Molar Mg# = Mg/(Mg+Fe), range (0, 1]. Controls how the mafic oxides mineralogy component, FmO, is split into FeO and MgO in the reverse pipeline.

Returns:

Bulk silicate composition as wt% oxides (SiO2, Al2O3, FeO, MgO, CaO), normalized to 100.

Return type:

dict[str, float]

stellar_geology.mineralogy.plot_norm(mineralogy)

Normalizes mineralogy to only olivine, clinopyroxene, and orthopyroxene for ternary plotting.

Parameters:

mineralogy (dict[str, float]) – Dictionary with key:value pairs as mineral name: proportion. Requires at minimum “olivine”, “clinopyroxene”, and “orthopyroxene”. All other key:value pairs will be ignored. Put whatever you want there, I don’t care. But you won’t get it returned to you.

Returns:

Mineralogy normalized to ol, opx, and cpx only.

Return type:

dict[str, float]

Conversions

Chemistry conversion functions imported by planet and star

stellar_geology.conversions.calculate_bulk_planet_from_dex(stellar_dex)

Runs all intermediate calculations to go directly from star composition in dex notation to bulk planet in wt% oxides. This is the most common use case, but allows the other intermediate methods to be exposed for benchmarking and debugging.

Parameters:

stellar_dex (dict[str, float]) – Star composition in dex notation.

Returns:

Bulk planet composition in wt% oxides.

Return type:

dict[str, float]

stellar_geology.conversions.calculate_dex_from_bulk_planet(wtpt_oxides)

Run the full reverse pipeline from bulk planet wt% oxides to dex notation.

Counterpart to calculate_bulk_planet_from_dex(). Chains all intermediate reverse steps: wtpt_oxides → wtpt_elements → total_wt_atoms → atoms_ref_solar → ax → dex.

The recovered dex values preserve interelemental ratios perfectly but are shifted by a constant offset relative to the original dex values (see CAVEATS.md for details). Volatile elements (C, O, S) present in the original stellar dex are not recoverable from oxide data.

Parameters:

wtpt_oxides (dict[str, float]) – Bulk planet composition in wt% oxides.

Returns:

Stellar composition in dex notation (relative values).

Return type:

dict[str, float]

stellar_geology.conversions.convert_composition(wtpt_oxides, units)

Convert a composition in wt% oxides to any supported unit system.

This is the main dispatcher for all unit conversions. It takes a canonical wt% oxides dict and converts it to the requested units by: 1. Computing raw numerators via the appropriate helper 2. Dividing by the sum to complete the conversion 3. Scaling to the target (100 for percent, 1.0 for fraction)

Parameters:

• wtpt_oxides (dict[str, float]) – Composition in wt% oxides (oxide keys, values summing to ~100).

• units (str) – Target unit string. One of: ‘wtpt_oxides’, ‘wtpt_elements’, ‘wtfrac_oxides’, ‘wtfrac_elements’, ‘molfrac_oxides’, ‘molfrac_elements’, ‘molfrac_singleO’, ‘molpt_oxides’, ‘molpt_elements’.

Returns:

Composition in the requested units.

Return type:

dict[str, float]

Raises:

ValueError – If units is not a recognized unit string.

stellar_geology.conversions.convert_to_wtpt_oxides(composition, from_units)

Convert a composition from any supported unit system back to wt% oxides.

This is the inverse of convert_composition(). Takes a dict in any supported unit and returns wt% oxides (oxide keys, values summing to 100).

Parameters:

• composition (dict[str, float]) – Composition in the units specified by from_units.

• from_units (str) – Unit string describing the input. One of the strings in VALID_UNITS.

Returns:

Composition in wt% oxides, normalized to sum to 100.

Return type:

dict[str, float]

Raises:

ValueError – If from_units is not a recognized unit string.

stellar_geology.conversions.normalize_composition(composition, units)

Rescale a composition dict so its values sum to the target for the given units (100 for percent units, 1.0 for fraction units).

Note that convert_composition() already normalizes outputs to its target (except for molfrac_singleO, see docs). This is a helper function to allow the user to easily perform normalization within their own scripts and essentially exists for convenience.

Parameters:

• composition (dict[str, float]) – Composition to normalize.

• units (str) – Any valid unit string from VALID_UNITS except 'molfrac_singleO' — singleO values are cations per oxygen atom, not parts of a whole, so sum-rescaling would distort their meaning.

Returns:

Normalized composition.

Return type:

dict[str, float]

Raises:

ValueError – If units is invalid or is 'molfrac_singleO'.

stellar_geology.conversions.wtpt_oxides_to_mol_oxides(wtpt_oxides)

Convert from wt% oxides to mol fraction oxides.

Parameters:

wtpt_oxides (dict[str, float]) – Composition in wt% oxides.

Returns:

Composition in mol fraction oxides, normalized to sum to 1.0.

Return type:

dict[str, float]

stellar_geology.conversions.wtpt_oxides_to_mol_cations(wtpt_oxides)

Convert from wt% oxides to mol fraction cations.

Parameters:

wtpt_oxides (dict[str, float]) – Composition in wt% oxides.

Returns:

Composition in mol fraction cations (element keys), normalized to sum to 1.0.

Return type:

dict[str, float]

stellar_geology.conversions.wtpt_oxides_to_mol_singleO(wtpt_oxides)

Convert from wt% oxides to moles of cations per single oxygen atom.

Parameters:

wtpt_oxides (dict[str, float]) – Composition in wt% oxides.

Returns:

Composition as cation moles normalized to one oxygen atom (element keys). Not normalized to sum to 1.0.

Return type:

dict[str, float]

stellar_geology.conversions.mol_oxides_to_wtpt_oxides(mol_oxides)

Convert from mol fraction oxides to wt% oxides.

Parameters:

mol_oxides (dict[str, float]) – Composition in mol fraction oxides.

Returns:

Composition in wt% oxides, normalized to sum to 100.

Return type:

dict[str, float]

stellar_geology.conversions.mol_cations_to_wtpt_oxides(mol_cations)

Convert from mol fraction cations to wt% oxides.

Parameters:

mol_cations (dict[str, float]) – Composition in mol fraction cations (element keys).

Returns:

Composition in wt% oxides, normalized to sum to 100.

Return type:

dict[str, float]

stellar_geology.conversions.mol_oxides_to_mol_cations(mol_oxides)

Convert from mol fraction oxides to mol fraction cations.

Parameters:

mol_oxides (dict[str, float]) – Composition in mol fraction oxides.

Returns:

Composition in mol fraction cations (element keys), normalized to sum to 1.0.

Return type:

dict[str, float]

stellar_geology.conversions.mol_cations_to_mol_oxides(mol_cations)

Convert from mol fraction cations to mol fraction oxides.

Parameters:

mol_cations (dict[str, float]) – Composition in mol fraction cations (element keys).

Returns:

Composition in mol fraction oxides, normalized to sum to 1.0.

Return type:

dict[str, float]

Data

Constants

Geochemical constants used throughout stellar_geology.

Includes atomic and oxide molar masses, solar abundance references, and mapping dictionaries between oxide and element representations.

stellar_geology.constants.filter_compositional_keys(comp, label='composition')

Warn about and remove non-compositional keys from a composition dict.

Accepts plain dicts or pandas Series (converted via .to_dict()).

Return type:

dict[str, float]