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

# Weighted modes transport

> Use WEIGHTED_MODES transport operations to calculate probability weighted emissions across multiple possible transport operations.

Weighted modes transport operations model a single shipment leg when the exact transport operation is unknown, but the possible alternatives and their probabilities or shares are known.
Set the transport operation `type` to `WEIGHTED_MODES` within a [transport chain](/content/guides/transport-chains) when a leg should be calculated as the weighted average of several possible
[`AIR`](/content/guides/air-transport), [`RAIL`](/content/guides/rail-transport), [`ROAD`](/content/guides/road-transport), or [`WATER`](/content/guides/water-transport) operations.

TerraTwin calculates each underlying transport operation between the same origin and destination boundaries, then combines the results using the percentage assigned to each operation.
This makes `WEIGHTED_MODES` useful for probability based emissions, fleet-mix modelling, lane-level service mixes, and policy scenarios where the shipment could have moved in one of several known ways.

<Columns cols={2}>
  <Card title="Mode" icon="circle-nodes">
    Use `type: "WEIGHTED_MODES"` in a `transportChain` transport element.

    TerraTwin treats that element as a single requested leg with several possible underlying transport operations.
  </Card>

  <Card title="Weights" icon="percent">
    Use `weightedTransportOperations` to list the alternatives.

    Each alternative has a `percent` value. The percentages must sum to `100`.
  </Card>

  <Card title="Operations" icon="layer-group">
    Each weighted item contains a full transport operation.

    The same mode can appear multiple times with different properties, or the alternatives can use different modes.
  </Card>

  <Card title="Result" icon="scale-balanced">
    TerraTwin returns one combined `WEIGHTED_MODES` result.

    The response also includes the weighted child results, showing the contribution from each alternative.
  </Card>
</Columns>

<Note>
  `WEIGHTED_MODES` does not perform sampling or simulation. It calculates all provided operations and combines
  them according to their assigned percentages.
</Note>

***

## Basic shape

A weighted modes operation needs `type: "WEIGHTED_MODES"` and a `weightedTransportOperations` array.
Each item in the array contains a `percent` and a nested `transportOperation`.

For example, a carrier may know that `40%` of the cargo on a lane between Madrid and Milan is transported by rail,
while the remaining `60%` moves by water.

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 250,
      "unit": "KILOGRAM"
    }
  },
  "origin": {
    "type": "PLACE",
    "city": "Madrid",
    "countryCode": "ES"
  },
  "destination": {
    "type": "PLACE",
    "city": "Milan",
    "countryCode": "IT"
  },
  "transportChain": [
    {
      "type": "WEIGHTED_MODES",
      "weightedTransportOperations": [
        {
          "percent": 40,
          "transportOperation": {
            "type": "RAIL"
          }
        },
        {
          "percent": 60,
          "transportOperation": {
            "type": "WATER"
          }
        }
      ]
    }
  ]
}
```

<Frame caption="Madrid to Milan by `RAIL` (40%) and `WATER` (60%)">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/weighted-mode-transport/madrid-to-milan-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=72f1fc37378974670877cee16ecd829b" width="1108" height="724" data-path="images/weighted-mode-transport/madrid-to-milan-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/weighted-mode-transport/madrid-to-milan-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=3229679cf946d4807b4bacf3b0f3417f" width="1108" height="724" data-path="images/weighted-mode-transport/madrid-to-milan-dark.png" />
</Frame>

The same pattern also works when the possible operations use the same transport mode.
For example, a carrier may know that a lane is served by a fleet with `20%` electric vehicle capacity and `80%` diesel vehicle capacity,
without knowing which vehicle served a particular package.

The same approach can also be used when the route itself is uncertain.
For example, a carrier may know that `70%` of containerized cargo moving between Asia and Europe travels via the Suez Canal,
while the remaining `30%` travels around Africa. `WEIGHTED_MODES` can model both water transport operations and combine them according to the expected route mix.

```json theme={null}
{
  "cargo": {
    "category": "MANUFACTURED_PRODUCTS",
    "weight": {
      "value": 12,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "HARBOR",
    "unLoCode": "CNSHK"
  },
  "destination": {
    "type": "HARBOR",
    "unLoCode": "NLRTM",
  },
  "transportChain": [
    {
      "type": "WEIGHTED_MODES",
      "weightedTransportOperations": [
        {
          "percent": 70,
          "transportOperation": {
            "type": "WATER",
            "vehicle": "CONTAINER",
            "size": "ULTRA_LARGE"
          }
        },
        {
          "percent": 30,
          "transportOperation": {
            "type": "WATER",
            "vehicle": "CONTAINER",
            "size": "ULTRA_LARGE",
            "navigationConstraints": [
                "AVOID_NORTHEAST_PASSAGE",
                "AVOID_NORTHWEST_PASSAGE",
                "AVOID_SUEZ_CANAL"
            ]            
          }
        }
      ]
    }
  ]
}
```

<Frame caption="Port of Shekou [`CNSHK`] to the Port of Rotterdam [`NLRTM`] - 70% via Suez Canal and 30% around Cape of Good Hope">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/weighted-mode-transport/shekou-to-rotterdam-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=2fa53ac9ceff5b17f5bf20f8ab22204a" width="1079" height="674" data-path="images/weighted-mode-transport/shekou-to-rotterdam-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/weighted-mode-transport/shekou-to-rotterdam-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=5497ee1214c013531c0bbbd90ff2a43b" width="1079" height="674" data-path="images/weighted-mode-transport/shekou-to-rotterdam-dark.png" />
</Frame>

***

## Properties

Weighted modes transport has a small top-level shape. The top-level object identifies the transport type and contains the list of weighted alternatives.

| Property                                                               | Required | What it does                                                                                                                                                               |
| ---------------------------------------------------------------------- | -------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <code className="whitespace-nowrap">type</code>                        |      Yes | Selects weighted modes transport. Use `WEIGHTED_MODES`.                                                                                                                    |
| <code className="whitespace-nowrap">weightedTransportOperations</code> |      Yes | Array of weighted transport operation objects. Each item defines one alternative operation and its percentage contribution. Percentages across all items must sum to `100` |

Each item in `weightedTransportOperations` describes one possible transport operation and the weighting applied to it.

| Property                                                      | Required | What it does                                                                                                             |
| ------------------------------------------------------------- | -------: | ------------------------------------------------------------------------------------------------------------------------ |
| <code className="whitespace-nowrap">percent</code>            |      Yes | Percentage weighting for the alternative. Must be greater than `0` and at most `100`. Decimal percentages are supported. |
| <code className="whitespace-nowrap">transportOperation</code> |      Yes | The underlying transport operation to calculate. Use an `AIR`, `RAIL`, `ROAD`, `WATER`, or `UNKNOWN` operation object.   |

The nested `transportOperation` uses the same properties as the equivalent operation in a normal transport chain.
For example, a nested `ROAD` operation can use `grossWeightBand`, `vehicle`, `energyType`, `loadFactor`, `emptyRunning`, and `energyConsumption`; a nested `WATER` operation can use `vehicle`, `capacity`, `size`, `containerTypeCode`, and `navigationConstraints`.

<Warning>
  `WEIGHTED_MODES` cannot contain another `WEIGHTED_MODES` operation as a nested alternative.
  If a scenario has nested probability branches, flatten the branches into one `weightedTransportOperations` array whose percentages still sum to `100`.
</Warning>

***

## Selecting weighted modes as the transport type

The mode is selected with the `type` property on the transport operation:

```json theme={null}
{
  "transportChain": [
    {
      "type": "WEIGHTED_MODES",
      "weightedTransportOperations": [
        {
          "percent": 50,
          "transportOperation": {
            "type": "ROAD"
          }
        },
        {
          "percent": 50,
          "transportOperation": {
            "type": "RAIL"
          }
        }
      ]
    }
  ]
}
```

The weighted operation runs between the nearest transport chain boundaries.
Those boundaries come from the top-level `origin` and `destination`, or from surrounding `HUB` elements in a larger `transportChain`.

The nested alternatives do not define their own origins or destinations.
They are operation definitions that inherit the same start and end boundaries from the parent `WEIGHTED_MODES` element.

```json theme={null}
{
  "cargo": {
    "category": "MANUFACTURED_PRODUCTS",
    "weight": {
      "value": 1,
      "unit": "METRIC_TONNE"
    }
  },
  "origin": {
    "type": "PLACE",
    "postcode": "G13 1EU",
    "city": "Glasgow",
    "countryCode": "GB"
  },
  "destination": {
    "type": "PLACE",
    "postcode": "MD-2023",
    "city": "Chișinău",
    "countryCode": "MD"
  },
  "transportChain": [
    {
      "type": "RAIL"
    }, {
      "type": "HUB",
      "location": {
        "type": "PLACE",
        "city": "London",
        "postcode": "N15",
        "countryCode": "GB"
      }
    }, {
      "type": "WEIGHTED_MODES",
      "weightedTransportOperations": [
        {
          "percent": 85,
          "transportOperation": {
            "type": "WATER",
            "vehicle": "CONTAINER",
            "size": "POST_PANAMAX"
          }
        }, {
          "percent": 15,
          "transportOperation": {
            "type": "AIR",
            "vehicle": "AIRBUS_A330_200F_FREIGHTER"
          }
        }
      ]
    }, {
      "type": "HUB",
      "location": {
        "type": "PLACE",
        "city": "Bucharest",
        "postcode": "061129",
        "countryCode": "RO"
      }
    }, {
      "type": "RAIL"
    }
  ]
}
```

In this larger chain, the weighted leg is bounded by the London and Bucharest hub elements.
Before the weighted leg, goods move by rail from the Glasgow industrial site to the London warehouse,
and after it, they continue by rail from Bucharest to Chișinău.

Within the weighted leg, `WEIGHTED_MODES` models two alternatives:

* Express air freight via Heathrow and Otopeni `15%` of the time.
* Sea freight via the ports of Tilbury and Constanța for the remaining `85%`.

The required hub and connection elements are inserted automatically along each alternative:

* Road connections to and from the air and sea hubs.
* Transshipment hubs for the air route.
* Marine terminal hubs for the sea route.

<Frame caption="Glasgow to Chișinău, with the London–Bucharest leg modelled as either standard `WATER` delivery (85%) or express `AIR` delivery (15%)">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/weighted-mode-transport/glasgow-to-chisinau-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=6d0b31d82b5e7c89e9a888c7a2b4799b" width="1222" height="876" data-path="images/weighted-mode-transport/glasgow-to-chisinau-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/weighted-mode-transport/glasgow-to-chisinau-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=5dc0b0c6481b236b0f8af0a99fc9f708" width="1222" height="876" data-path="images/weighted-mode-transport/glasgow-to-chisinau-dark.png" />
</Frame>

<Note>
  The London and Bucharest hubs omit `hubType`.
  For `WEIGHTED_MODES`, TerraTwin evaluates each possible incoming/outgoing mode pair and uses the hub type with the highest emissions intensity.
  Set `hubType` explicitly when the facility type is known. See [Weighted modes transitions](/content/guides/hubs#weighted-modes-transitions).
</Note>

***

## What the percentages mean

`percent` is the weighting applied to each alternative transport operation.
The percentages are expressed as values out of `100` and must sum to `100` across the `weightedTransportOperations` array.

The meaning of the weighting depends on what the request is modelling. In each case, the percentages should use a consistent basis across all alternatives.

| Situation                                    | How to interpret `percent`                                                                                |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Unknown operation for an individual shipment | The likelihood that the shipment used each alternative operation.                                         |
| Fleet or capacity mix                        | The share of available capacity represented by each vehicle class, energy type, or service configuration. |
| Lane-level service mix                       | The share of transport activity on the lane handled by each mode, route, service level, or carrier.       |
| Scenario modelling                           | The assumed share assigned to each scenario being compared or combined.                                   |

`percent` is not the same as `loadFactor`, `emptyRunning`, cargo weight, or vehicle utilization.
Use the mode-specific properties inside the nested `transportOperation` to describe how full the vehicle was, how much empty running occurred, which fuel was used, or which vessel, aircraft, train, or truck was selected.

<Warning>
  Do not base `percent` on vehicle counts unless each vehicle provides a comparable share of transport capacity or activity.
  Use a consistent basis across all alternatives, such as probability, capacity share, shipment share, or lane activity share.
</Warning>

***

## Same mode weighting

Use same-mode weighting when every alternative uses the same transport mode, but differs by vehicle type, energy source, route, or service level.
The same mode can appear multiple times in `weightedTransportOperations`.

Common examples include:

| Scenario                       | Example modelling pattern                                                                 | Example                                                                                                                                                                                                                                                              |
| ------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Road fleet energy mix          | Multiple `ROAD` operations with the same vehicle class but different `energyType` values. | A carrier knows that available capacity on a lane is `20%` electric vehicles using `ELECTRICITY`, `75%` diesel vehicles using `DIESEL`, and `5%` vehicles using fossil-free diesel with `HVO100`.                                                                    |
| Road vehicle class uncertainty | Multiple `ROAD` operations with different vehicle classes or configurations.              | A carrier knows that `30%` of deliveries on a lane are made by vans using `LCV_BELOW_3500_KG`, while the remaining `70%` are made by `MEDIUM_DUTY_VEHICLE`.                                                                                                          |
| Vessel routing uncertainty     | Multiple `WATER` operations with different navigation constraints.                        | A carrier knows that `70%` of containerized cargo between Asia and Europe travels via the Suez Canal, while the remaining `30%` travels around Africa.                                                                                                               |
| Vessel type uncertainty        | Multiple `WATER` operations with different vessel types.                                  | A shipper knows that a product is shipped `40%` of the time as breakbulk palletized cargo on `GENERAL_CARGO` vessels, and `60%` of the time on `CONTAINER` vessels.                                                                                                  |
| Vessel size uncertainty        | Multiple `WATER` operations with the same vessel type but different vessel sizes.         | A carrier operates two `GENERAL_CARGO` vessels on the same lane: one with a deadweight tonnage of `3500` tonnes and one with a deadweight tonnage of `6500` tonnes. Where the vessels are used equally, the capacity-weighted split is `35%` and `65%` respectively. |
| Aircraft uncertainty           | Multiple `AIR` operations with different aircraft types or aircraft categories.           | A carrier knows that express freight on a lane is carried `80%` of the time on an Airbus A330 freighter, and `20%` of the time on another freighter aircraft type.                                                                                                   |

***

## Different mode weighting

Use different-mode weighting when the same leg may be carried by different transport modes.
Each alternative is still a complete transport operation with its own mode specific modelling inputs.

Common examples include:

| Scenario                   | Example modelling pattern                                                                             | Example                                                                                                                                                                |
| -------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Emergency replenishment    | One `WATER` operation for standard replenishment and one `AIR` operation for emergency replenishment. | A shipper knows that replenishment between two warehouses moves by sea `98%` of the time, but by air `2%` of the time when emergency stock is required.                |
| Road and rail service mix  | One `ROAD` operation and one `RAIL` operation for the same lane.                                      | A carrier knows that `60%` of containerized cargo between two hubs moves by articulated truck, while the remaining `40%` moves by container train.                     |
| Road and water service mix | One `ROAD` operation and one `WATER` operation for the same lane.                                     | A shipper knows that cargo moves by short-sea service `85%` of the time, but by road `15%` of the time when sailing schedules do not align with delivery requirements. |
| Air and road service mix   | One `AIR` operation and one `ROAD` operation for the same lane.                                       | A carrier knows that `20%` of shipments between two sites use express air service, while the remaining `80%` use standard road service.                                |

This example extends the road and rail service mix pattern by adding a water alternative.
It models containerized cargo moving from the Port of Toronto to a warehouse in Vancouver as a weighted mix of three alternatives:

* `70%` moves by container train using a `RAIL` operation.
* `25%` moves by articulated truck using a `ROAD` operation.
* `5%` moves by `POST_PANAMAX` container ship using a `WATER` operation.

```json theme={null}
{
  "cargo": {
    "weight": {
      "value": 50,
      "unit": "KILOGRAM"
    }
  },
  "origin": {
    "type": "HARBOR",
    "unLoCode": "CAVAN"
  },
  "destination": {
    "type": "PLACE",
    "postcode": "M9W",
    "countryCode": "CA"
  },
  "transportChain": [
    {
      "type": "WEIGHTED_MODES",
      "weightedTransportOperations": [
        {
          "percent": 70,
          "transportOperation": {
            "type": "RAIL",
            "energyType": "DIESEL"
          }
        }, {
          "percent": 25,
          "transportOperation": {
            "type": "ROAD",
            "structure": "ARTICULATED",
            "grossWeight": {
              "value": 44000,
              "unit": "KILOGRAM"
            }            
          }
        }, {
          "percent": 5,
          "transportOperation": {
            "type": "WATER",
            "vehicle": "CONTAINER",
            "size": "POST_PANAMAX"
          }
        }
      ]
    }
  ]
}
```

<Frame caption="Vancouver to Toronto by diesel-electric train (70%), articulated truck (25%) and post-panamax container ship (5%)">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/weighted-mode-transport/vancouver-to-toronto-light.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=babfbed27aad8c57a3d11de18d53eb56" width="1052" height="732" data-path="images/weighted-mode-transport/vancouver-to-toronto-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/xfw_jqxWpPnqzdZT/images/weighted-mode-transport/vancouver-to-toronto-dark.png?fit=max&auto=format&n=xfw_jqxWpPnqzdZT&q=85&s=ac4f395672a1360e850145d7f794fe79" width="1052" height="732" data-path="images/weighted-mode-transport/vancouver-to-toronto-dark.png" />
</Frame>

The water alternative will select suitable harbors, insert marine terminal hubs, and may add road connector movements.

The rail alternative will select suitable rail terminals and may add road connector movements.

An air alternative would similarly select suitable airports, insert transshipment hubs, and may add road connector movements.

<Note>
  Weighted mode alternatives do not need to have the same realized structure.
  One child may realize as a direct road movement, while another may realize as first-mile road, hub, rail, hub, and last-mile road.
  TerraTwin weights the fully realized result for each alternative.
</Note>