Loss calc

Preview API

This endpoint is marked as a preview API. Preview APIs may be unstable within the preview period: they may change without notice. You must set the header API-Preview: opt-in to opt into using this endpoint.

Simulations create an ensemble with multiple values for every grid block, comprising a probabilistic estimate of what's underground. The loss calc task takes that ensemble and uses a loss function to put blocks into categories, such as ore or waste.

The task looks at the simulated values for each block and calculates the expected loss of including or excluding that block from each category. Then, it assigns the block to the category where the expected loss of including the block is lower than the expected loss of excluding it. If that's true for more than one category, the block will go into whichever of those is last in your list of categories.

Let $S$ be the simulation results, where $S_{ij}$ is the simulated value of block $i$ in realization $j$.

For each category, let:

• $g$ be the cutoff grade,
• $r$ be the metal recovery fraction,
• $p$ be the metal price,
• $c_t$ be the processing cost,
• $c_w$ be the mining waste cost,
• $c_o$ be the mining ore cost,
• $p_o(i)$ be the empirical probability that block $i$ is above the cutoff grade $g$¹,
• $m_+(i)$ be the conditional mean of simulated values at block $i$ that are above the cutoff grade $g$²,
• $m_-(i)$ be the conditional mean of simulated values at block $i$ that are below the cutoff grade $g$³.,

Then, the expected loss from excluding block $i$ from the category is

$L_{w}(i)=p_o(i) \cdot (p \cdot r \cdot m_+(i) - c_t - c_o + c_w)$

And the expected loss from including block $i$ in the category is

$L_{o}(i)=( 1 - p_o(i) ) \cdot ( c_t + c_o - p \cdot r \cdot m_-(i) - c_w)$

If $L_{w}(i) < L_{o}(i)$, then block $i$ is assigned to the category.

Parameters

• source (geoscience object reference)
  • A geoscience object reference that points to a multi-dimensional continuous attribute inside a regular-3d-grid or regular-masked-3d-grid object. This is the ensemble you want to compute the loss function over.
• target (geoscience object reference)
  • A geoscience object reference that tells the task where to save the result. It must point to an attribute inside a regular-3d-grid or regular-masked-3d-grid object. The task will save a categorical attribute there, where each block is assigned one of the categories you define.
• material_categories (list of objects)
  • A list of categories. The task will put blocks into these categories.

  • [
        {"cutoff_grade": 0.50, "metal_price": 1.0, "label": "waste"},
        {"cutoff_grade": 5.00, "metal_price": 3.0, "label": "gold"},
    ]
• processing_cost (number)
  • How much it costs to process a block of material.
• mining_waste_cost (number)
  • How much it costs to mine a block of waste.
• mining_ore_cost (number)
  • How much it costs to mine a block of ore.
• metal_recovery_fraction (number)
  • The proportion of metal that you can recover from a block of ore. This is a number between 0 and 1.

Example

Request

requests.post(
    "https://{hub}.api.seequent.com/compute/orgs/{org_id}/geostat/loss-calc",
    headers={"Authorization": "Bearer {token}"},
    json={
        "parameters": {
            "source": {
                "type": "geoscience-object-reference",
                "object_reference": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-grid.json",
                "object_element": [
                    {
                        "type": "element",
                        "path": "/cell_attributes/@name=my-ensemble",
                    },
                ],
            },
            "target": {
                "type": "geoscience-object-reference",
                "object_reference": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-grid.json",
                "object_element": [
                    {
                        "type": "element",
                        "path": "/cell_attributes/@name=my-loss",
                    },
                ],
            },
            "material_categories": [
                {"cutoff_grade": 0.50, "metal_price": 1.0, "label": "waste"},
                {"cutoff_grade": 5.00, "metal_price": 3.0, "label": "gold"},
            ],
            "processing_cost": 30.00,
            "mining_waste_cost": 20.00,
            "mining_ore_cost": 20.00,
            "metal_recovery_fraction": 0.4,
        },
    },
)

Result

{
    "message": "Calculation completed",
    "object_modified": {
        "type": "geoscience-object-reference",
        "object_reference": "https://{hub}.api.seequent.com/geoscience-object/orgs/{org_id}/workspaces/{workspace_id}/objects/path/my-grid.json",
        "object_element": [
            {
                "type": "element",
                "path": "/cell_attributes/@name=my-loss",
            },
        ],
    },
}

Tips

• The source and target can use the same object, but they don't have to.

Footnotes

1. The empirical probability is computed by counting how many realizations of the block are above the cutoff grade, divided by the total number of realizations, i.e.

   $p_o(i) = P(S_i > g) = \frac{1}{n} \sum_{j=1}^{n} \mathbf{1}_{\{ S_{ij} > g \}}$ ↩

2. The conditional mean is computed by taking the mean of the simulated values that are above the cutoff grade, divided by the number of realizations that are above the cutoff grade, i.e.

   $m_+(i) = \frac{\sum_{j=1}^{n} S_{ij} \, \mathbf{1}_{\{ S_{ij} > x \}}}{\sum_{j=1}^{n} \mathbf{1}_{\{ S_{ij} > x \}}}$ ↩

3. The conditional mean is computed by taking the mean of the simulated values that are below the cutoff grade, divided by the number of realizations that are below the cutoff grade, i.e.

   $m_-(i)=\frac{\sum_{j=1}^{n} S_{ij} \, \mathbf{1}_{\{ S_{ij} < x \}}}{\sum_{j=1}^{n} \mathbf{1}_{\{ S_{ij} > x \}}}$ ↩