> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heychocolate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scenario Simulator

> Run what-if analyses to explore how different choices affect sustainability outcomes.

The Scenario Simulator is a sandbox environment where you can modify parameters — materials, transport methods, energy sources — and instantly see how they affect the impact score. Source data is never mutated.

## How it works

A scenario takes an existing product or calculation as a baseline and applies one or more parameter overrides. The engine returns both the original and modified scores for comparison.

## Running a scenario

```graphql theme={null}
mutation {
  simulateScenario(input: {
    baseProductId: "prod_abc123"
    quantity: 100
    overrides: [
      { parameter: MATERIAL, value: "bio_based_composite" },
      { parameter: TRANSPORT_METHOD, value: "RAIL" },
      { parameter: ENERGY_SOURCE, value: "SOLAR" }
    ]
  }) {
    baseline {
      co2Equivalent
      mkiScore
    }
    simulated {
      co2Equivalent
      mkiScore
    }
    delta {
      co2Equivalent
      mkiScore
      percentageChange
    }
    equivalency {
      description
      value
    }
  }
}
```

**Response:**

```json theme={null}
{
  "data": {
    "simulateScenario": {
      "baseline": {
        "co2Equivalent": 1240.0,
        "mkiScore": 87.0
      },
      "simulated": {
        "co2Equivalent": 680.0,
        "mkiScore": 47.6
      },
      "delta": {
        "co2Equivalent": -560.0,
        "mkiScore": -39.4,
        "percentageChange": -45.2
      },
      "equivalency": {
        "description": "This saves the equivalent of",
        "value": "2,170 km of car driving"
      }
    }
  }
}
```

## Available override parameters

| Parameter          | Type   | Description                                      |
| ------------------ | ------ | ------------------------------------------------ |
| `MATERIAL`         | String | Replace material composition                     |
| `TRANSPORT_METHOD` | Enum   | `TRUCK`, `RAIL`, `SHIP`, `AIR`, `ELECTRIC_TRUCK` |
| `ENERGY_SOURCE`    | Enum   | `GRID`, `SOLAR`, `WIND`, `HYDRO`, `NATURAL_GAS`  |
| `ORIGIN_COUNTRY`   | String | ISO country code for sourcing origin             |
| `PACKAGING`        | String | Packaging material type                          |
| `RECYCLED_CONTENT` | Float  | Percentage of recycled material (0-100)          |
| `END_OF_LIFE`      | Enum   | `LANDFILL`, `RECYCLE`, `INCINERATE`, `COMPOST`   |

## Multi-scenario comparison

Compare multiple scenarios side-by-side:

```graphql theme={null}
mutation {
  simulateScenarios(input: {
    baseProductId: "prod_abc123"
    quantity: 100
    scenarios: [
      {
        name: "Bio-based + Rail"
        overrides: [
          { parameter: MATERIAL, value: "bio_based_composite" },
          { parameter: TRANSPORT_METHOD, value: "RAIL" }
        ]
      },
      {
        name: "Recycled + Electric"
        overrides: [
          { parameter: RECYCLED_CONTENT, value: "80" },
          { parameter: TRANSPORT_METHOD, value: "ELECTRIC_TRUCK" }
        ]
      }
    ]
  }) {
    baseline { co2Equivalent mkiScore }
    results {
      name
      simulated { co2Equivalent mkiScore }
      delta { percentageChange }
    }
  }
}
```

## Use cases

* **E-commerce**: Show customers how choosing a different delivery method reduces impact
* **Procurement**: Evaluate supplier alternatives before making purchasing decisions
* **Product development**: Test material choices during the design phase
* **Reporting**: Model future reduction targets for CSRD/ESG reports