oreblocks

Software note (CC-BY-4.0): "oreblocks: License-Free Synthetic Ore-Body Block Models with a Stamped Exact Ultimate-Pit Optimum", concept DOI 10.5281/zenodo.21512088 (source in manuscripts/ore-body-twins/). It gives the deposit archetypes, the exact max-closure ultimate-pit solver, and an independent LP cross-check to machine precision (~1e-15).

Synthetic 3-D ore-body block models of the MineLib nature, and their scheduling, seeded deposit archetypes with per-block grades, bench (level) structure, slope precedence, UPIT economics with per-block optimal destination, an exact max-closure solver, extraction states with loading faces, MineLib .blocks/.prec/.upit/.cpit/.pcpsp read/write, the certified CPIT LP bound by the critical multiplier algorithm, the TopoSort rounding heuristics, and spatial-coherence metrics. Deterministic given a seed; every generated instance is clearly labelled SYNTHETIC.

Why: per-block ground truth on real mines is licensed or proprietary (MineLib grants academic download only, no redistribution). oreblocks generates instances of the same nature, 3-D benches, grades, precedence, net values, with a stamped exact optimum, so solvers, dispatch simulators and teaching apps get license-free realistic instances with known-by-construction answers.

Install

pip install oreblocks

Quickstart: a MineLib-format twin with a stamped optimum

from oreblocks import make_twin

twin = make_twin("porphyry", dims=(20, 20, 10), seed=42)
print(twin.upit.pit_value, twin.upit.n_in_pit)   # the EXACT optimum, stamped
twin.write("out/")   # -> twin-*.blocks / .prec / .upit / .meta.json (MineLib format)

The emitted triplet is byte-consumable by any MineLib UPIT reader. Cross-validated against an independent TypeScript min-cut engine (CAOS PitForge, which reproduces the published newman1 / zuck_small / kd optima): relative disagreement ~1e-11 on a 4,000-block twin.

Scheduling: which blocks, and WHEN

The ultimate pit says which blocks are worth mining. The constrained pit limit problem (CPIT) says when: assign every block a period so slope precedence holds in every period, per-period capacities hold, and discounted value is maximised. It is NP-hard, so what ships is a certified upper bound plus feasible schedules, with the gap between them reported rather than hidden.

import oreblocks as ob

inst = ob.read_cpit("newman1.cpit")                    # periods, discount rate, capacities
prec = ob.read_prec("newman1.prec", inst.n_blocks)
result, relaxations = ob.solve_cpit(inst, prec)        # bound, schedule, local search
print(f"{result.npv:,.0f}  bound {result.bound:,.0f}  gap {result.gap_pct:.2f}%")

controls = ob.run_controls(inst, prec, result)         # duality, bound, order invariance
assert controls.all_pass

The bound needs no LP solver. Chicoisne et al. 2012 (Operations Research 60(3):517-528, doi:10.1287/opre.1120.1050, Theorem 3.1) show the CPIT LP relaxation is solved exactly in O(mn log n) for one resource per period, as a sequence of parametric nested pits, which are maximum closures, which this package already computes exactly.

On the published newman1.cpit with its two resources, Algorithm 4 (one resource relaxed at a time) returns 24 487 410 and the joint Bienstock-Zuckerberg bound (cpit_bz_bound) returns 24 486 184, which is the CPIT LP upper bound MineLib publishes for that instance. On newman1.pcpsp, where the model also chooses each block's destination, pcpsp_lp_bound returns 24 486 549, the published PCPSP LP upper bound (Jelvez, Morales and Nancel-Penard 2018, Table 3). The PCPSP bound sits above the CPIT one because PCPSP is the richer problem.

Full detail, including the three file-format traps and the explicit list of what is not implemented (stockpiles, blending, minimum-production constraints, two-stage stochastic scheduling): docs/scheduling.md.

Pieces

Convention notes

• Levels (z) increase upward: level 0 is the deepest bench: exactly how published MineLib instances index (verified against newman1). Depth-down viewers flip with z_down = nz-1-level.
• .blocks free columns written by oreblocks are documented in the meta sidecar: grade (mass fraction) · tonnage (t) · density (t/m³).
• Nothing here downloads or redistributes published MineLib data.

Used by

• minehaulsim (haulage DES): geology-grounded scenarios: loading faces with grade/bench.
• CAOS PitForge: license-free synthetic twins next to the published-instance lane.

License

MIT, as LICENSE and pyproject.toml state.