⛏️ minproc — Mineral Processing Toolkit

Pure-Python calculations for mineral processing & extractive metallurgy — zero dependencies, unit-tested, ready for coursework, lab reports, and quick plant math.

English below · Bahasa Indonesia di bawah 🇮🇩

---

Why this exists

Every metallurgy student and junior plant engineer ends up re-deriving the same calculations — the two-product formula, Bond mill energy, P80 from sieve data, percent solids from a Marcy scale reading — in ad-hoc spreadsheets that are easy to get subtly wrong. minproc packages these classic calculations as small, documented, tested Python functions with textbook references, so you can spend your time on interpretation instead of formula plumbing.

• 🐍 Pure Python — no NumPy, no SciPy, nothing to install beyond Python 3.9+
• ✅ Unit-tested against hand-checked textbook values (pytest + CI)
• 📚 Documented — every function cites its formula and reference
• 🎓 Built for learning — readable source you can open and study

Installation

pip install git+https://github.com/Foxvi124/mineral-processing-toolkit.git

or clone and install locally (editable, nice for tinkering):

git clone https://github.com/Foxvi124/mineral-processing-toolkit.git
cd mineral-processing-toolkit
pip install -e .

Quick start

import minproc as mp

# 1) Metallurgical balance of a flotation stage — from assays alone
mp.two_product(feed=2.0, conc=10.0, tail=0.5)
# {'yield_pct': 15.79, 'recovery_pct': 78.95,
#  'ratio_of_concentration': 6.33, 'enrichment_ratio': 5.0}

# 2) Grinding energy by Bond's law (F80, P80 in micrometres)
mp.bond_energy(work_index=12.0, f80=12700, p80=100)     # 10.94 kWh/t
mp.bond_power(12.0, 12700, 100, throughput=200)         # 2187 kW

# 3) Sieve analysis -> P80 -> distribution model
table = mp.sieve_analysis(
    apertures=[4.0, 2.0, 1.0, 0.5, 0.25, 0],            # mm (0 = pan)
    mass_retained=[5, 10, 20, 30, 25, 10],              # g
)
mp.p80(table)                                           # 1.68 mm
sizes   = [r["aperture"]    for r in table if r["aperture"] > 0]
passing = [r["cum_passing"] for r in table if r["aperture"] > 0]
m, k, r2 = mp.fit_ggs(sizes, passing)                   # Gates-Gaudin-Schuhmann

# 4) Is gravity separation feasible? (gold vs quartz in water)
cc = mp.concentration_criterion(rho_heavy=19.3, rho_light=2.65)  # 11.09
mp.interpret_cc(cc)   # 'Easy: gravity separation effective down to ...'

# 5) Slurry math for pump and thickener sizing
mp.pulp_density(pct_solids=30, rho_solids=2.7)          # 1.233 t/m3
mp.flow_rates(dry_tph=100, pct_solids=30, rho_solids=2.7)
# {'water_tph': 233.3, 'pulp_tph': 333.3, 'pulp_m3ph': 270.4, ...}

# 6) Leaching kinetics — Shrinking Core Model
mp.scm_time_fraction(0.5, "reaction")                   # t/tau = 0.206
mp.scm_conversion(t=30, tau=120, mechanism="diffusion") # X at t = 30
mp.activation_energy(k1=1e-3, t1=300, k2=2e-3, t2=310)  # Ea in J/mol

Run the full tour:

python examples/quickstart.py

What's inside

Module	Functions	Core formulas
comminution	bond_energy, bond_power, reduction_ratio, rittinger_energy, kick_energy	$W = 10,W_i\left(\tfrac{1}{\sqrt{P_{80}}} - \tfrac{1}{\sqrt{F_{80}}}\right)$
concentration	two_product, recovery, separation_efficiency, concentration_criterion, interpret_cc	$R = \tfrac{c,(f-t)}{f,(c-t)} \times 100%$, $CC = \tfrac{\rho_h - \rho_f}{\rho_l - \rho_f}$
sizing	sieve_analysis, passing_size, p80, fit_ggs, fit_rosin_rammler	$Y = 100(x/k)^m$, $Y = 100\left(1 - e^{-(x/x')^n}\right)$
slurry	pulp_density, pct_solids_from_density, pct_solids_by_volume, dilution_ratio, flow_rates	$C_w = \tfrac{100,\rho_s(\rho_p - \rho_l)}{\rho_p(\rho_s - \rho_l)}$
kinetics	scm_time_fraction, scm_conversion, arrhenius_k, activation_energy	$\tfrac{t}{\tau} = 1 - 3(1{-}X)^{2/3} + 2(1{-}X)$ (ash diffusion)

Main references: Wills & Finch, Wills' Mineral Processing Technology (8th ed.); Levenspiel, Chemical Reaction Engineering (3rd ed.).

Running the tests

pip install pytest
pytest

Roadmap

Contributions in any of these directions are very welcome:

• Flotation kinetics (first-order rate models, kinetic flotation tests)
• Gy's sampling equation and sampling-error estimation
• Hydrocyclone models (Plitt) and partition curves
• Three-product formula and n-product node balancing
• Pourbaix / Nernst helpers for hydrometallurgy
• A small Streamlit web calculator on top of this package
• Bahasa Indonesia docstrings / dokumentasi dwibahasa

Contributing

Found a bug, want a formula added, or spotted a better reference? Open an issue or a pull request — see CONTRIBUTING.md. Adding a single well-tested function is a perfect first contribution.

Disclaimer

This library is intended for education and preliminary engineering estimates. Always verify results independently before using them for design decisions, safety-related work, or commercial commitments.

License

MIT © 2026 Alfonsus Abdi

---

🇮🇩 Bahasa Indonesia

minproc adalah pustaka Python murni (tanpa dependensi) berisi perhitungan-perhitungan klasik pengolahan mineral dan metalurgi ekstraktif: rumus dua produk (recovery, yield, ratio of concentration), energi penggerusan Bond, analisis ayak dan P80, model distribusi ukuran (GGS dan Rosin-Rammler), persen solid dan densitas pulp, kriteria konsentrasi gravitasi, hingga kinetika pelindian dengan Shrinking Core Model.

Semua fungsi terdokumentasi lengkap dengan rumus dan acuan pustaka, serta teruji dengan unit test terhadap nilai hitungan manual dari buku teks — cocok untuk mahasiswa Teknik Metalurgi/Pertambangan yang mengerjakan laporan praktikum maupun engineer yang butuh perhitungan cepat di lapangan.

Instalasi

pip install git+https://github.com/Foxvi124/mineral-processing-toolkit.git

Contoh singkat

import minproc as mp

# Neraca metalurgi satu tahap flotasi, cukup dari kadar saja
mp.two_product(feed=2.0, conc=10.0, tail=0.5)   # recovery 78.9%

# Energi penggerusan Bond (F80 dan P80 dalam mikrometer)
mp.bond_energy(work_index=12.0, f80=12700, p80=100)   # 10.94 kWh/t

# Persen solid dari densitas pulp (skala Marcy)
mp.pct_solids_from_density(rho_pulp=1.233, rho_solids=2.7)   # ≈ 30%

Kontribusi

Isu, saran rumus baru, dan pull request sangat diterima — termasuk dokumentasi berbahasa Indonesia. Lihat CONTRIBUTING.md.

Catatan

Pustaka ini ditujukan untuk pembelajaran dan estimasi awal. Selalu verifikasi hasil perhitungan secara independen sebelum dipakai untuk keputusan desain atau pekerjaan yang menyangkut keselamatan.