mineralco 1.0.0

MINERALCO: Computational Mineralogy, Crystallographic Physics & High-Pressure Phase Dynamics

💎 MINERALCO

Computational Mineralogy, Crystallographic Physics & High-Pressure Phase Dynamics

Seven parameters to decode the Earth's solid core. — Samir Baladi, March 2026

---

Overview

MINERALCO (Mineral Intelligence Network for Equation-of-state Research, Atomic Lattice COmputation) is an open-source Python framework for the systematic characterisation of mineral behaviour under the extreme pressure and temperature conditions prevailing throughout Earth's crust, mantle, and core.

The framework introduces the Crystal Intelligence Septuplet (CIS) — a unified seven-parameter system that simultaneously encodes all information required to predict a mineral's equation of state, thermal expansion, phase stability, and lattice energy under any pressure-temperature combination accessible within Earth (0.1 MPa → 363 GPa; 300 K → 6,000 K).

MINERALCO was validated against 3,200 experimental P-V-T data points for 47 mantle and core minerals, achieving a mean RMS volumetric prediction error of 0.19% and correctly predicting phase transition onset for 43 of 47 benchmark minerals (91.5%).

The project now features a live interactive dashboard connected to a PostgreSQL database with 19 benchmark minerals and real-time CSI calculations.

---

Table of Contents

• The Crystal Intelligence Septuplet

• Key Results

• Installation

• Quick Start

• Project Structure

• Module Reference

• Benchmark Minerals

• Dashboard

• Citation

• Author

• License

---

🔷 The Crystal Intelligence Septuplet

MINERALCO is built around exactly seven physically non-redundant parameters — the CIS — that fully parameterise the third-order Birch-Murnaghan EOS and the Mie-Grüneisen thermal pressure correction:

#	Parameter	Symbol	Physical Domain	Role
1	Bulk Modulus	K₀	Elasticity / Solid Mechanics	Zero-pressure incompressibility; primary EOS stiffness parameter; controls seismic velocity and density at depth
2	Lattice Parameters	a, b, c (α,β,γ)	Crystallography / Atomic Geometry	Unit cell edge lengths and angles; encode atomic bond lengths, densities, and anisotropy; measured by X-ray diffraction
3	Pressure Derivative	K'	Non-linear Elasticity	First pressure derivative ∂K/∂P at P=0; quantifies stiffness increase under compression; critical above ~10 GPa
4	Crystal Symmetry	Sᵧ	Crystallographic Group Theory	Space group (1–230) and crystal system (cubic → triclinic); determines Madelung constant, elastic anisotropy, and independent elastic constants
5	Thermal Expansion	α	Thermodynamics / Crystal Physics	Volumetric thermal expansion ∂(lnV)/∂T
6	Grüneisen Parameter	γ	Thermodynamics / Lattice Dynamics	Dimensionless coupling γ = αKₛV/Cᵥ; links thermal pressure to volume; backbone of the Mie-Grüneisen EOS
7	Specific Volume	Vₛ	Equation of State	Molar volume V = M/ρ (cm³/mol); primary observable in synchrotron P-V experiments; dependent variable in all EOS fitting

Why exactly seven? Fewer loses essential physical information (the Sᵧ–K' correlation breaks without explicit symmetry parameterisation; the Grüneisen self-consistency test cannot be performed without independent α and γ). The eighth potentially meaningful parameter K'' is predicted by BM3 theory as K'' = K'(K'−4)/K₀ + 35/9K₀ — carrying no independent information beyond K₀ and K'.

---

📊 Key Results

H1 — EOS Accuracy (✅ Confirmed)

Mean RMS volumetric prediction error of 0.19% across 3,200 P-V-T data points for 47 benchmark minerals (0–363 GPa, 300–5,000 K). Target: ≤ 0.30%.

Mineral	K₀ (GPa)	K'	RMS ΔV/V	Data Points
Forsterite Mg₂SiO₄	128.4 ± 1.8	4.31 ± 0.08	0.11%	318 / 0–20 GPa
Wadsleyite β-Mg₂SiO₄	172.3 ± 3.2	4.26 ± 0.12	0.18%	212 / 14–22 GPa
Ringwoodite γ-Mg₂SiO₄	185.1 ± 2.9	4.14 ± 0.09	0.14%	187 / 18–24 GPa
Bridgmanite MgSiO₃	260.7 ± 3.8	3.97 ± 0.11	0.22%	394 / 25–130 GPa
Post-perovskite MgSiO₃	229.8 ± 7.2	4.02 ± 0.18	0.28%	147 / 120–135 GPa
Ferropericlase (Mg,Fe)O	162.3 ± 2.1	3.84 ± 0.07	0.09%	421 / 0–150 GPa
ε-Iron hcp-Fe	163.4 ± 9.1	5.38 ± 0.31	0.29%	228 / 50–363 GPa
ALL 47 MINERALS	—	—	0.19%	3,200 pts

H2 — Phase Transition Prediction (✅ 91.5% accuracy)

Crystal Stability Index (CSI) correctly predicts phase transition onset within ±1.5 GPa for 43 of 47 benchmark minerals, including all four major seismic discontinuities:

Phase Transition	P_exp (GPa)	P_MINERALCO (GPa)	CSI	Seismic Feature
Olivine → Wadsleyite	13.5 ± 0.3	13.8	0.86	410 km discontinuity
Wadsleyite → Ringwoodite	18.0 ± 0.5	18.3	0.88	520 km discontinuity
Ringwoodite → Bridgmanite + FP	23.5 ± 0.4	23.2	0.91	660 km discontinuity
Bridgmanite → Post-perovskite	125 ± 2	124	0.87	D'' layer (~2,600 km)
ε-Fe → Liquid Iron	330 ± 5	327	0.93	Inner Core Boundary

H3 — Grüneisen Self-Consistency (✅ Confirmed)

Thermodynamic and phonon Grüneisen parameters agree to r² = 0.971 across 28 minerals, confirming that MINERALCO CIS is thermodynamically self-consistent rather than empirically over-parameterised.

H4 — Symmetry-Stiffness Paradigm (✅ Confirmed, r = −0.88)

Crystal symmetry class Sᵧ is a statistically significant predictor of pressure derivative K' (Pearson r = −0.88, p < 0.001):

Crystal System	K' Mean	K' Std Dev	N Minerals
Cubic	4.01	± 0.24	11
Tetragonal	4.18	± 0.31	4
Hexagonal / Trigonal	4.29	± 0.38	8
Orthorhombic	4.44	± 0.41	15
Monoclinic	4.67	± 0.52	6
Triclinic	4.91	± 0.61	3

Bridgmanite → PREM Validation

Seven-parameter CIS predicts PREM seismic velocities at 660 km depth without any empirical adjustment:

Observable	MINERALCO	PREM	Discrepancy
Vₚ (km/s)	10.23	10.27	0.4%
Vₛ (km/s)	5.57	5.57	< 0.1%
Density (g/cm³)	4.378	4.380	0.05%

---

📦 Installation

pip install meneralco

PyPI: https://pypi.org/project/meneralco/

Requirements: Python 3.11+, NumPy, SciPy, Matplotlib, Pandas

Or install from source:

git clone https://gitlab.com/gitdeeper9/mineralco.git
cd mineralco
pip install -e .

---

⚡ Quick Start

from mineralco import EOSFitter, ThermalCorrector, PhaseMapper, LatticeAnalyzer

# --- 1. Fit BM3-EOS to P-V data ---
fitter = EOSFitter()
result = fitter.fit_bm3(
    pressure=[0, 5, 10, 15, 20],          # GPa
    volume=[43.79, 42.10, 40.58, 39.18, 37.88],  # cm³/mol
    mineral="forsterite"
)
print(result)
# K0 = 128.4 ± 1.8 GPa | K' = 4.31 ± 0.08 | V0 = 43.79 cm³/mol

# --- 2. Apply Mie-Grüneisen thermal correction ---
thermal = ThermalCorrector(K0=128.4, Kp=4.31, V0=43.79, gamma=1.21, alpha=2.85e-5)
P_at_T = thermal.pressure(V=40.0, T=1800)   # GPa at mantle conditions

# --- 3. Analyse unit cell geometry ---
lattice = LatticeAnalyzer(a=4.756, b=10.207, c=5.980, alpha=90, beta=90, gamma=90)
print(lattice.crystal_system)   # "Orthorhombic"
print(lattice.V0)               # 43.79 cm³/mol
print(lattice.K_prime_prior)    # 4.44 ± 0.41  (from Sᵧ-K' correlation)

# --- 4. Compute Crystal Stability Index ---
mapper = PhaseMapper()
csi = mapper.csi(K0=185.1, Vs=39.49, Kp=4.14, Sy="cubic", alpha=2.10e-5, gamma=1.27)
print(f"CSI = {csi:.2f}")      # CSI = 0.91  → phase transition imminent

---

🌐 Live Dashboard

Access the interactive dashboard at mineralco.netlify.app/dashboard

Dashboard Features:

· 19 minerals with real-time CIS parameters from PostgreSQL database · CSI calculator with 7-parameter weighted formula · Interactive map with 43 experimental sites worldwide · EOS chart for bridgmanite P-V data · Parameter weights visualization · Auto-refresh every 30 seconds

API Endpoints:

· GET /api/minerals - All minerals with CIS parameters · GET /api/latest-csi - Current CSI for bridgmanite · GET /api/stats - Database statistics

---

🗂 Project Structure

mineralco/
│
├── mineralco/                      # Core Python package
│   ├── __init__.py                 # Package entry point; exports all public classes
│   ├── engine/
│   │   ├── eos_fitter.py           # EOSFitter — BM2/BM3/BM4 non-linear least squares fitting
│   │   ├── thermal_corrector.py    # ThermalCorrector — Mie-Grüneisen thermal EOS
│   │   ├── lattice_analyzer.py     # LatticeAnalyzer — unit cell geometry, Sᵧ classification
│   │   └── phase_mapper.py         # PhaseMapper — CSI computation, phase boundary mapping
│   ├── data/
│   │   ├── cis_database.json       # 47-mineral CIS parameter database (K₀, K', α, γ, Vₛ, Sᵧ)
│   │   ├── pvt_benchmark.csv       # 3,200 experimental P-V-T data points
│   │   ├── space_groups.json       # 230 space groups — Wyckoff positions, Madelung constants
│   │   └── prem_reference.csv      # PREM seismic reference model (density, Vₚ, Vₛ vs. depth)
│   ├── utils/
│   │   ├── unit_converter.py       # SI ↔ geophysics unit conversions (GPa, cm³/mol, K, km/s)
│   │   ├── debye_model.py          # Debye thermal energy and heat capacity functions
│   │   ├── born_lande.py           # Born-Landé lattice energy estimation
│   │   └── gruneisen.py            # Thermodynamic and phonon Grüneisen consistency checks
│   └── viz/
│       ├── eos_plotter.py          # P-V-T EOS curve plotting (matplotlib)
│       ├── phase_diagram.py        # P-T phase stability map visualisation
│       └── prem_comparison.py      # Seismic velocity vs. PREM comparison plots
│
├── Netlify/                         # Web dashboard and API
│   ├── functions/                    # Netlify Functions
│   │   ├── minerals.js
│   │   ├── latest-csi.js
│   │   └── stats.js
│   └── public/                       # Static files
│       ├── index.html
│       ├── dashboard.html
│       ├── reports.html
│       └── documentation.html
│
├── notebooks/                      # Jupyter notebooks — reproduce all manuscript figures
│   ├── 01_bm3_eos_fitting.ipynb
│   ├── 02_thermal_correction_mie_gruneisen.ipynb
│   ├── 03_csi_phase_prediction.ipynb
│   └── ... (15 notebooks total)
│
├── tests/                          # Unit and integration tests
├── docs/                           # Documentation source
├── data/                           # Raw benchmark data
├── paper/
│   └── MINERALCO_RESEARCH_PAPER.pdf   # Submitted manuscript
├── pyproject.toml                  # Build system configuration
├── setup.cfg                       # Package metadata and dependencies
├── requirements.txt                # Python dependencies
├── LICENSE                         # MIT License
├── CHANGELOG.md                    # Version history
└── README.md                       # This file

---

🔧 Module Reference

EOSFitter

Fits the third-order Birch-Murnaghan EOS to experimental or DFT P-V data.

from mineralco import EOSFitter

fitter = EOSFitter()
result = fitter.fit_bm3(pressure, volume, mode="BM3")
# mode: "BM2" (K' fixed=4.0) | "BM3" (standard) | "BM4" (K'' free)

result.K0           # Bulk modulus ± 1σ (GPa)
result.Kp           # Pressure derivative ± 1σ
result.V0           # Zero-pressure volume ± 1σ (cm³/mol)
result.rms_error    # RMS ΔV/V
result.covariance   # Full parameter covariance matrix
result.plot()       # EOS curve with residuals

BM3-EOS implemented:

P(V) = (3K₀/2) · [(V₀/V)^(7/3) − (V₀/V)^(5/3)] · {1 + (3/4)(K'−4) · [(V₀/V)^(2/3) − 1]}

---

ThermalCorrector

Mie-Grüneisen thermal EOS with Debye thermal energy model.

from mineralco import ThermalCorrector

tc = ThermalCorrector(K0=261, Kp=3.97, V0=24.45, gamma=1.57, alpha=2.0e-5)
P = tc.pressure(V=19.8, T=2500)       # Pressure at given V and T (GPa)
V = tc.volume(P=80, T=2500)           # Volume at given P and T (cm³/mol)
tc.plot_pvt_surface(P_max=135, T_max=3000)

Thermal pressure:

P(V,T) = P_BM3(V,T_ref) + (γ/V) · [E_th(T) − E_th(T_ref)]

---

LatticeAnalyzer

Unit cell geometry, crystal system classification, and Born-Landé lattice energy.

from mineralco import LatticeAnalyzer

lattice = LatticeAnalyzer(a=4.775, b=4.929, c=6.897)
lattice.crystal_system      # "Orthorhombic"
lattice.V0                  # 24.45 cm³/mol
lattice.K_prime_prior       # 4.44 ± 0.41
lattice.madelung_constant   # Lookup by crystal system
lattice.born_lande_energy(Z_plus=2, Z_minus=-2, n=9)  # Lattice energy (kJ/mol)

---

PhaseMapper

Crystal Stability Index computation and P-T phase boundary mapping.

from mineralco import PhaseMapper

mapper = PhaseMapper()
csi = mapper.csi(K0=185.1, Vs=39.49, Kp=4.14, Sy="cubic",
                 alpha=2.10e-5, gamma=1.27, phi_latt=None)
# CSI ≥ 0.85 → transition imminent (within ±2 GPa in 87% of benchmark cases)

mapper.phase_boundary(mineral_a="ringwoodite", mineral_b="bridgmanite")
mapper.plot_stability_map(mineral="forsterite", P_max=25, T_max=2000)

CSI formula:

CSI = 0.28·K₀* + 0.19·Vₛ* + 0.17·K'* + 0.13·Sᵧ* + 0.10·α* + 0.09·γ* + 0.04·Φ*_lattice

---

🪨 Benchmark Minerals

MINERALCO v1.0 includes CIS parameters for 47 minerals spanning all major mantle lithologies. The 15 key minerals from Appendix A:

Mineral K₀ (GPa) K' α (×10⁻⁵ K⁻¹) γ V₀ (cm³/mol) System Quality Periclase MgO 160.3±0.8 3.99±0.03 3.12 1.524 11.25 Cubic ★★★★★ Forsterite Mg₂SiO₄ 128.4±1.8 4.31±0.08 2.85 1.21 43.79 Orthorhombic ★★★★★ Enstatite MgSiO₃ 108.5±2.1 7.00±0.22 2.61 1.01 31.28 Orthorhombic ★★★★☆ Wadsleyite β-Mg₂SiO₄ 172.3±3.2 4.26±0.12 2.43 1.21 40.52 Monoclinic ★★★★☆ Ringwoodite γ-Mg₂SiO₄ 185.1±2.9 4.14±0.09 2.10 1.27 39.49 Cubic ★★★★★ Bridgmanite MgSiO₃ 260.7±3.8 3.97±0.11 2.00 1.57 24.45 Orthorhombic ★★★★★ Post-perovskite MgSiO₃ 229.8±7.2 4.02±0.18 1.80 1.48 24.09 Orthorhombic ★★★☆☆ Ferropericlase (Mg,Fe)O 162.3±2.1 3.84±0.07 3.07 1.50 11.49 Cubic ★★★★★ Majorite MgSiO₃ 165.1±4.1 4.32±0.17 2.35 1.18 39.63 Cubic ★★★★☆ Corundum Al₂O₃ 252.2±2.4 4.27±0.09 1.68 1.32 25.58 Trigonal ★★★★★ Stishovite SiO₂ 313.1±3.1 3.82±0.08 1.58 1.35 14.01 Tetragonal ★★★★★ ε-Iron hcp-Fe 163.4±9.1 5.38±0.31 3.50 1.78 6.74 Hexagonal ★★★☆☆ Diopside CaMgSi₂O₆ 112.5±3.2 4.51±0.21 3.18 1.11 66.09 Monoclinic ★★★★☆ Grossular Ca₃Al₂Si₃O₁₂ 168.9±2.8 4.23±0.11 1.84 1.06 125.28 Cubic ★★★★☆ Kyanite Al₂SiO₅ 193.0±5.1 4.62±0.28 1.41 0.98 44.09 Triclinic ★★★☆☆

---

🌐 Dashboard

Interactive P-V-T EOS calculator and phase stability maps:

mineralco.netlify.app — Landing page mineralco.netlify.app/dashboard — Live dashboard with 19 minerals and real-time CSI mineralco.netlify.app/reports — Phase stability reports

---

📄 Citation

If you use MINERALCO in your research, please cite:

Primary Paper

@article{baladi2026mineralco,
  author    = {Baladi, Samir},
  title     = {{MINERALCO}: A Seven-Parameter Atomic Architecture Framework for Mineral Phase
               Intelligence — Equation of State Modelling, Lattice Thermodynamics \&
               Mantle Phase Transition Prediction},
  journal   = {Physics and Chemistry of Minerals},
  publisher = {Springer},
  year      = {2026},
  month     = {March},
  note      = {Submitted},
  doi       = {10.5281/zenodo.19009597},
  url       = {https://doi.org/10.5281/zenodo.19009597},
  orcid     = {0009-0003-8903-0029}
}

Software (Zenodo)

@software{baladi2026mineralco_software,
  author    = {Baladi, Samir},
  title     = {{MINERALCO} v1.0.0: Computational Mineralogy, Crystallographic Physics
               \& High-Pressure Phase Dynamics},
  year      = {2026},
  month     = {March},
  publisher = {Zenodo},
  version   = {v1.0.0},
  doi       = {10.5281/zenodo.19009597},
  url       = {https://doi.org/10.5281/zenodo.19009597}
}

PyPI Package

@misc{baladi2026mineralco_pypi,
  author    = {Baladi, Samir},
  title     = {meneralco: MINERALCO Python Package — Seven-Parameter Mineral
               Phase Intelligence on PyPI},
  year      = {2026},
  url       = {https://pypi.org/project/meneralco/},
  note      = {pip install meneralco}
}

Plain-text citation

Baladi, S. (2026). MINERALCO: A Seven-Parameter Atomic Architecture Framework for Mineral Phase Intelligence — Equation of State Modelling, Lattice Thermodynamics & Mantle Phase Transition Prediction. Submitted to Physics and Chemistry of Minerals (Springer). DOI: 10.5281/zenodo.19009597. Software: https://pypi.org/project/meneralco/

---

👤 Author

Samir Baladi (Git8) Interdisciplinary AI Researcher Ronin Institute / Rite of Renaissance

📧 [e-mail] 🔬 ORCID: 0009-0003-8903-0029 📦 PyPI: pypi.org/project/meneralco 🌐 mineralco.netlify.app 📁 GitLab: gitlab.com/gitdeeper9/mineralco 📁 GitHub: github.com/gitdeeper9/mineralco

---

📋 Data & Code Availability

All benchmark datasets, CIS parameter databases, and source code are fully open-access:

Resource Link GitLab (primary) gitlab.com/gitdeeper9/mineralco GitHub (mirror) github.com/gitdeeper9/mineralco Zenodo DOI 10.5281/zenodo.19009597 PyPI package pypi.org/project/meneralco Dashboard mineralco.netlify.app Submitted paper Physics and Chemistry of Minerals (Springer)

---

📜 License

This project is licensed under the MIT License — see LICENSE for details.

---

🗓 Changelog

See CHANGELOG.md for version history.

v1.0.0 — March 2026 — Initial release. 47-mineral benchmark, BM3/BM4 EOS fitting, Mie-Grüneisen thermal correction, CSI phase stability mapping, Born-Landé lattice energy, Grüneisen self-consistency test, interactive dashboard with PostgreSQL database and live API.

---

💎 MINERALCO — Seven parameters to decode the Earth's solid core.