oreblocks 0.1.0__py3-none-any.whl

oreblocks/__init__.py

@@ -0,0 +1,46 @@
+"""oreblocks — synthetic 3-D ore-body block models of the MineLib nature.
+
+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, and MineLib ``.blocks/.prec/.upit`` read/write. Everything deterministic given a
+seed; every generated instance is clearly labelled SYNTHETIC.
+"""
+
+__version__ = "0.1.0"
+
+from .economics import Econ, block_values, cutoff_grade, is_ore
+from .extraction import ExtractionState, Face, extraction_state, loading_faces
+from .fields import ARCHETYPES, Deposit, make_deposit
+from .grid import BlockGrid
+from .minelib_io import read_blocks, read_meta, read_prec, read_upit, write_minelib
+from .precedence import Precedence, build_precedence, slope_offsets
+from .twins import Twin, make_twin
+from .upit import UpitResult, solve_upit
+
+__all__ = [
+    "__version__",
+    "ARCHETYPES",
+    "BlockGrid",
+    "Deposit",
+    "Econ",
+    "ExtractionState",
+    "Face",
+    "Precedence",
+    "Twin",
+    "UpitResult",
+    "block_values",
+    "build_precedence",
+    "cutoff_grade",
+    "extraction_state",
+    "is_ore",
+    "loading_faces",
+    "make_deposit",
+    "make_twin",
+    "read_blocks",
+    "read_meta",
+    "read_prec",
+    "read_upit",
+    "slope_offsets",
+    "solve_upit",
+    "write_minelib",
+]

oreblocks/_rng.py

@@ -0,0 +1,20 @@
+"""Seeded, named random streams — same discipline as minehaulsim.
+
+Every stochastic component draws from its own named stream derived from (seed, name), so adding a
+new consumer never perturbs existing draws and results are byte-identical given the seed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+import numpy as np
+
+__all__ = ["stream"]
+
+
+def stream(seed: int, name: str) -> np.random.Generator:
+    """A generator for the (seed, name) pair — stable across platforms and numpy versions."""
+    digest = hashlib.sha256(f"{seed}:{name}".encode()).digest()
+    words = [int.from_bytes(digest[k : k + 4], "little") for k in range(0, 16, 4)]
+    return np.random.Generator(np.random.PCG64(np.random.SeedSequence(words)))

oreblocks/economics.py

@@ -0,0 +1,54 @@
+"""Block economics — the UPIT value model with per-block optimal destination.
+
+A block's net value is the better of its two destinations, exactly the semantics of a MineLib
+``.upit`` column (verified against newman1, where the published net value equals
+max(value-if-wasted, value-if-processed)):
+
+- waste:   ``-mining_cost * tonnage``
+- ore:     ``(grade * recovery * price - processing_cost) * tonnage - mining_cost * tonnage``
+
+The floating cutoff falls out of the max: a block is ore iff processing it beats wasting it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .fields import Deposit
+
+__all__ = ["Econ", "block_values", "is_ore", "cutoff_grade"]
+
+
+@dataclass(frozen=True)
+class Econ:
+    """price: $/t of recovered metal · recovery: 0..1 · costs: $/t mined / $/t milled."""
+
+    price: float = 9000.0
+    recovery: float = 0.88
+    mining_cost: float = 2.5
+    processing_cost: float = 9.0
+
+    def __post_init__(self) -> None:
+        if not (0 < self.recovery <= 1):
+            raise ValueError(f"recovery must be in (0,1], got {self.recovery}")
+        if self.price <= 0 or self.mining_cost < 0 or self.processing_cost < 0:
+            raise ValueError("price must be positive; costs non-negative")
+
+
+def cutoff_grade(econ: Econ) -> float:
+    """The grade above which processing beats wasting: processing_cost / (recovery * price)."""
+    return econ.processing_cost / (econ.recovery * econ.price)
+
+
+def block_values(dep: Deposit, econ: Econ) -> np.ndarray:
+    """Net value per block (float64) at the optimal destination — the ``.upit`` column."""
+    waste = -econ.mining_cost * dep.tonnage
+    ore = (dep.grade * econ.recovery * econ.price - econ.processing_cost) * dep.tonnage + waste
+    return np.maximum(waste, ore)
+
+
+def is_ore(dep: Deposit, econ: Econ) -> np.ndarray:
+    """Boolean per block: does processing beat wasting?"""
+    return dep.grade > cutoff_grade(econ)

oreblocks/extraction.py

@@ -0,0 +1,177 @@
+"""Extraction state + loading faces — the bridge from a static pit to an OPERATING mine.
+
+Given the exact pit (``in_pit``) and a mining progress fraction, benches are extracted top-down
+(the only physical order): the state says which levels are fully out, which level is the active
+bench, and which pit blocks remain. Loading FACES are seeded k-means clusters of the remaining
+active-bench blocks — each face is a shovel position with its local mean grade, ore/waste split
+and available tonnage. This is what a haulage simulator (e.g. minehaulsim) consumes to ground
+truck cycles in geology: grade at face, bench elevation, ore vs waste destination.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from ._rng import stream
+from .economics import Econ, cutoff_grade
+from .fields import Deposit
+from .grid import BlockGrid
+
+__all__ = ["Face", "ExtractionState", "extraction_state", "loading_faces"]
+
+
+@dataclass(frozen=True)
+class Face:
+    """One loading position on the active bench."""
+
+    face_id: int
+    level: int
+    x: float  # centroid, block units
+    y: float
+    n_blocks: int
+    tonnes: float
+    mean_grade: float
+    ore_fraction: float  # by tonnage, at the given cutoff
+    elevation_m: float  # level * dz (bench floor height above the deepest level)
+
+
+@dataclass(frozen=True)
+class ExtractionState:
+    """Benches above ``active_level`` are fully extracted (within the pit); the active bench is
+    partially extracted per ``progress``. ``remaining`` marks in-pit blocks not yet mined."""
+
+    active_level: int
+    progress: float
+    extracted: np.ndarray  # bool per block
+    remaining: np.ndarray  # bool per block (in_pit & ~extracted)
+    tonnes_extracted: float
+    tonnes_remaining: float
+
+
+def _pit_levels(grid: BlockGrid, in_pit: np.ndarray) -> list[int]:
+    """Levels that contain pit blocks, ordered TOP-DOWN (mining order)."""
+    per = grid.nx * grid.ny
+    levels = [lv for lv in range(grid.nz) if in_pit[lv * per : (lv + 1) * per].any()]
+    return list(reversed(levels))
+
+
+def extraction_state(dep: Deposit, in_pit: np.ndarray, progress: float, seed: int = 1) -> ExtractionState:
+    """Extract ``progress`` (0..1) of the pit TONNAGE top-down; the active bench is partial.
+
+    Within the active bench, blocks leave in a seeded deterministic order (a centre-out sweep with
+    jitter), so a given (pit, progress, seed) always yields the same state.
+    """
+    if not (0.0 <= progress <= 1.0):
+        raise ValueError(f"progress must be in [0,1], got {progress}")
+    grid = dep.grid
+    in_pit = np.asarray(in_pit, dtype=bool)
+    total = float(dep.tonnage[in_pit].sum())
+    target = progress * total
+    extracted = np.zeros(grid.n_blocks, dtype=bool)
+    mined = 0.0
+    active = grid.surface_level
+    per = grid.nx * grid.ny
+    rng = stream(seed, "extraction:order")
+
+    for lv in _pit_levels(grid, in_pit):
+        active = lv
+        sl = slice(lv * per, (lv + 1) * per)
+        idxs = np.nonzero(in_pit[sl])[0] + lv * per
+        lv_tonnes = float(dep.tonnage[idxs].sum())
+        if mined + lv_tonnes <= target or lv_tonnes == 0.0:
+            extracted[idxs] = True
+            mined += lv_tonnes
+            if mined >= target:
+                break
+            continue
+        # partial bench: deterministic centre-out order with seeded jitter
+        ix = idxs % grid.nx
+        iy = (idxs // grid.nx) % grid.ny
+        cx = (grid.nx - 1) / 2.0
+        cy = (grid.ny - 1) / 2.0
+        key = np.hypot(ix - cx, iy - cy) + 0.25 * rng.random(idxs.shape[0])
+        order = idxs[np.argsort(key, kind="stable")]
+        csum = np.cumsum(dep.tonnage[order])
+        need = target - mined
+        k = 0 if need <= 0 else int(np.searchsorted(csum, need, side="left")) + 1
+        take = order[: min(k, order.shape[0])]
+        extracted[take] = True
+        mined += float(dep.tonnage[take].sum())
+        break
+
+    remaining = in_pit & ~extracted
+    return ExtractionState(
+        active_level=active,
+        progress=progress,
+        extracted=extracted,
+        remaining=remaining,
+        tonnes_extracted=mined,
+        tonnes_remaining=float(dep.tonnage[remaining].sum()),
+    )
+
+
+def loading_faces(
+    dep: Deposit,
+    state: ExtractionState,
+    econ: Econ,
+    n_faces: int = 3,
+    seed: int = 1,
+) -> list[Face]:
+    """Cluster the remaining ACTIVE-bench blocks into ``n_faces`` seeded k-means faces."""
+    if n_faces < 1:
+        raise ValueError("n_faces must be >= 1")
+    grid = dep.grid
+    per = grid.nx * grid.ny
+    lv = state.active_level
+    sl = slice(lv * per, (lv + 1) * per)
+    idxs = np.nonzero(state.remaining[sl])[0] + lv * per
+    if idxs.shape[0] == 0:  # bench exhausted: fall back to the next level with remaining blocks
+        rem_levels = [x for x in _pit_levels(grid, state.remaining) if state.remaining[x * per : (x + 1) * per].any()]
+        if not rem_levels:
+            return []
+        lv = rem_levels[0]
+        sl = slice(lv * per, (lv + 1) * per)
+        idxs = np.nonzero(state.remaining[sl])[0] + lv * per
+
+    ix = (idxs % grid.nx).astype(np.float64)
+    iy = ((idxs // grid.nx) % grid.ny).astype(np.float64)
+    pts = np.stack([ix, iy], axis=1)
+    k = min(n_faces, idxs.shape[0])
+
+    rng = stream(seed, f"faces:level{lv}")
+    centroids = pts[rng.choice(pts.shape[0], size=k, replace=False)]
+    assign = np.zeros(pts.shape[0], dtype=np.int64)
+    for _ in range(12):  # Lloyd iterations — plenty for bench-scale point sets
+        d2 = ((pts[:, None, :] - centroids[None, :, :]) ** 2).sum(axis=2)
+        assign = d2.argmin(axis=1)
+        for c in range(k):
+            sel = assign == c
+            if sel.any():
+                centroids[c] = pts[sel].mean(axis=0)
+
+    cutoff = cutoff_grade(econ)
+    faces: list[Face] = []
+    for c in range(k):
+        sel = idxs[assign == c]
+        if sel.shape[0] == 0:
+            continue
+        t = dep.tonnage[sel]
+        g = dep.grade[sel]
+        tt = float(t.sum())
+        ore_t = float(t[g > cutoff].sum())
+        faces.append(
+            Face(
+                face_id=c,
+                level=lv,
+                x=float(centroids[c, 0]),
+                y=float(centroids[c, 1]),
+                n_blocks=int(sel.shape[0]),
+                tonnes=tt,
+                mean_grade=float((g * t).sum() / tt) if tt > 0 else 0.0,
+                ore_fraction=ore_t / tt if tt > 0 else 0.0,
+                elevation_m=lv * grid.dz,
+            )
+        )
+    return faces

oreblocks/fields.py

@@ -0,0 +1,146 @@
+"""Seeded synthetic deposits — geostatistically plausible grade fields on a block grid.
+
+Clearly SYNTHETIC (no real drillholes), but built the way real deposits are described: a
+deterministic grade trend (the geological shape) plus spatially-correlated noise (a box-smoothed
+white field standing in for a variogram range), so downstream optimisers face non-trivial
+ore/waste and slope trade-offs. Everything is seeded — byte-identical given (archetype, dims,
+seed). The four archetypes mirror the CAOS PitForge teaching set:
+
+- ``porphyry``  — a buried ellipsoidal high-grade shell (broad bowl pits)
+- ``vein``      — a dipping tabular zone (narrow steep pits)
+- ``layered``   — horizontal stratabound bands
+- ``core_halo`` — a rich core inside a broad low-grade halo
+
+Levels increase UPWARD (grid convention); the trend functions are written in depth fractions so
+the shapes match their depth-down originals exactly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from ._rng import stream
+from .grid import BlockGrid
+
+__all__ = ["ARCHETYPES", "Deposit", "make_deposit"]
+
+ARCHETYPES = ("porphyry", "vein", "layered", "core_halo")
+
+
+@dataclass(frozen=True)
+class Deposit:
+    """A block model: grid + per-block grade (mass fraction), tonnage (t) and density (t/m3)."""
+
+    grid: BlockGrid
+    grade: np.ndarray
+    tonnage: np.ndarray
+    density: np.ndarray
+    meta: dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        n = self.grid.n_blocks
+        for name in ("grade", "tonnage", "density"):
+            a = getattr(self, name)
+            if a.shape != (n,):
+                raise ValueError(f"{name} must be a flat array of {n} blocks, got {a.shape}")
+
+
+def _smooth(vol: np.ndarray, passes: int) -> np.ndarray:
+    """A few 3x3x3 box-blur passes (edge-corrected) give white noise a correlation length."""
+    out = vol.astype(np.float64, copy=True)
+    ones = np.ones_like(out)
+    for _ in range(passes):
+        acc = np.zeros_like(out)
+        cnt = np.zeros_like(out)
+        for dz in (-1, 0, 1):
+            for dy in (-1, 0, 1):
+                for dx in (-1, 0, 1):
+                    src = out[
+                        max(0, -dz) : out.shape[0] - max(0, dz),
+                        max(0, -dy) : out.shape[1] - max(0, dy),
+                        max(0, -dx) : out.shape[2] - max(0, dx),
+                    ]
+                    csrc = ones[
+                        max(0, -dz) : out.shape[0] - max(0, dz),
+                        max(0, -dy) : out.shape[1] - max(0, dy),
+                        max(0, -dx) : out.shape[2] - max(0, dx),
+                    ]
+                    acc[
+                        max(0, dz) : out.shape[0] - max(0, -dz),
+                        max(0, dy) : out.shape[1] - max(0, -dy),
+                        max(0, dx) : out.shape[2] - max(0, -dx),
+                    ] += src
+                    cnt[
+                        max(0, dz) : out.shape[0] - max(0, -dz),
+                        max(0, dy) : out.shape[1] - max(0, -dy),
+                        max(0, dx) : out.shape[2] - max(0, -dx),
+                    ] += csrc
+        out = acc / cnt
+    return out
+
+
+def _trend(archetype: str, fx: np.ndarray, fy: np.ndarray, fdepth: np.ndarray) -> np.ndarray:
+    """Relative grade shape in ~[0,1]; ``fdepth`` = 0 at the surface, 1 at the deepest level."""
+    cx = fx - 0.5
+    cy = fy - 0.5
+    if archetype == "porphyry":
+        r = np.sqrt(cx * cx + cy * cy + (fdepth - 0.45) ** 2)
+        return np.maximum(0.0, 1.0 - np.abs(r - 0.22) / 0.28)
+    if archetype == "vein":
+        plane = cx * 0.8 + (fdepth - 0.5) * 0.6
+        return np.maximum(0.0, 1.0 - np.abs(plane) / 0.12)
+    if archetype == "layered":
+        return 0.5 + 0.5 * np.cos(fdepth * np.pi * 4)
+    if archetype == "core_halo":
+        r = np.sqrt(cx * cx + cy * cy + (fdepth - 0.5) ** 2)
+        return np.maximum(0.0, 1.0 - r / 0.45) ** 1.6
+    raise ValueError(f"unknown archetype {archetype!r}; expected one of {ARCHETYPES}")
+
+
+def make_deposit(
+    grid: BlockGrid,
+    archetype: str,
+    seed: int = 1,
+    *,
+    peak_grade: float = 0.02,
+    background: float = 0.001,
+    density: float = 2.7,
+    noise: float = 0.35,
+    name: str | None = None,
+) -> Deposit:
+    """Build a seeded synthetic deposit on ``grid``. Grades are mass fractions in [0, 1]."""
+    if archetype not in ARCHETYPES:
+        raise ValueError(f"unknown archetype {archetype!r}; expected one of {ARCHETYPES}")
+    rng = stream(seed, f"deposit:{archetype}")
+    white = rng.random((grid.nz, grid.ny, grid.nx)) - 0.5
+    corr = _smooth(white, passes=3)
+
+    level = np.arange(grid.nz, dtype=np.float64)
+    fdepth_1d = 1.0 - (level / (grid.nz - 1) if grid.nz > 1 else np.full(1, 0.5))
+    fx_1d = np.arange(grid.nx, dtype=np.float64) / (grid.nx - 1) if grid.nx > 1 else np.full(1, 0.5)
+    fy_1d = np.arange(grid.ny, dtype=np.float64) / (grid.ny - 1) if grid.ny > 1 else np.full(1, 0.5)
+    fdepth, fy, fx = np.meshgrid(fdepth_1d, fy_1d, fx_1d, indexing="ij")
+
+    shape = _trend(archetype, fx, fy, fdepth)
+    grade = background + (peak_grade - background) * np.maximum(0.0, shape + noise * corr)
+    grade = np.clip(grade, 0.0, 1.0).reshape(-1)
+
+    block_tonnes = grid.block_volume * density
+    return Deposit(
+        grid=grid,
+        grade=grade,
+        tonnage=np.full(grid.n_blocks, block_tonnes),
+        density=np.full(grid.n_blocks, density),
+        meta={
+            "archetype": archetype,
+            "seed": seed,
+            "peak_grade": peak_grade,
+            "background": background,
+            "noise": noise,
+            "grade_unit": "mass fraction",
+            "name": name or archetype,
+            "synthetic": True,
+        },
+    )

oreblocks/grid.py

@@ -0,0 +1,76 @@
+"""Regular 3-D block grid with MineLib's level convention.
+
+The vertical index is the LEVEL and increases UPWARD: level 0 is the deepest bench, level
+``nz - 1`` is the surface bench. This is the convention published MineLib instances use (verified
+against newman1: a block's predecessors sit one level ABOVE it), so everything oreblocks emits is
+directly comparable with the published library. Viewers that draw depth-down (z=0 at the surface)
+simply flip: ``z_down = (nz - 1) - level``.
+
+Flat indexing is ``index = (level * ny + iy) * nx + ix`` — x fastest, then y, then level.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+__all__ = ["BlockGrid"]
+
+
+@dataclass(frozen=True)
+class BlockGrid:
+    """Grid dimensions + block size (metres). ``nz`` counts benches (levels, up)."""
+
+    nx: int
+    ny: int
+    nz: int
+    dx: float = 10.0
+    dy: float = 10.0
+    dz: float = 10.0
+
+    def __post_init__(self) -> None:
+        if min(self.nx, self.ny, self.nz) < 1:
+            raise ValueError(f"grid dims must be >= 1, got {self.nx}x{self.ny}x{self.nz}")
+        if min(self.dx, self.dy, self.dz) <= 0:
+            raise ValueError("block size must be positive")
+
+    @property
+    def n_blocks(self) -> int:
+        return self.nx * self.ny * self.nz
+
+    @property
+    def surface_level(self) -> int:
+        return self.nz - 1
+
+    @property
+    def block_volume(self) -> float:
+        return self.dx * self.dy * self.dz
+
+    def index(self, ix: int, iy: int, level: int) -> int:
+        """Flat index of the block at (ix, iy, level). Bounds-checked."""
+        if not (0 <= ix < self.nx and 0 <= iy < self.ny and 0 <= level < self.nz):
+            raise IndexError(f"({ix},{iy},{level}) outside {self.nx}x{self.ny}x{self.nz}")
+        return (level * self.ny + iy) * self.nx + ix
+
+    def coords(self, i: int) -> tuple[int, int, int]:
+        """(ix, iy, level) of flat index ``i``."""
+        if not (0 <= i < self.n_blocks):
+            raise IndexError(f"flat index {i} outside 0..{self.n_blocks - 1}")
+        level, rem = divmod(i, self.nx * self.ny)
+        iy, ix = divmod(rem, self.nx)
+        return ix, iy, level
+
+    def coord_arrays(self) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """(x, y, level) int32 arrays for every block, in flat order — the MineLib id order."""
+        ii = np.arange(self.n_blocks, dtype=np.int64)
+        level, rem = np.divmod(ii, self.nx * self.ny)
+        iy, ix = np.divmod(rem, self.nx)
+        return ix.astype(np.int32), iy.astype(np.int32), level.astype(np.int32)
+
+    def level_slice(self, level: int) -> slice:
+        """Flat-index slice covering one whole level."""
+        if not (0 <= level < self.nz):
+            raise IndexError(f"level {level} outside 0..{self.nz - 1}")
+        per = self.nx * self.ny
+        return slice(level * per, (level + 1) * per)