Weighted modes transport - TerraTwin API Documentation

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 when a leg should be calculated as the weighted average of several possible AIR, RAIL, ROAD, or WATER 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.

Mode

Use type: "WEIGHTED_MODES" in a transportChain transport element.TerraTwin treats that element as a single requested leg with several possible underlying transport operations.

Weights

Use weightedTransportOperations to list the alternatives.Each alternative has a percent value. The percentages must sum to 100.

Operations

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.

Result

TerraTwin returns one combined WEIGHTED_MODES result.The response also includes the weighted child results, showing the contribution from each alternative.

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

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.

{
  "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"
          }
        }
      ]
    }
  ]
}

Madrid to Milan by `RAIL` (40%) and `WATER` (60%)

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.

{
  "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"
            ]            
          }
        }
      ]
    }
  ]
}

Port of Shekou [`CNSHK`] to the Port of Rotterdam [`NLRTM`] - 70% via Suez Canal and 30% around Cape of Good Hope

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
`type`	Yes	Selects weighted modes transport. Use `WEIGHTED_MODES`.
`weightedTransportOperations`	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
`percent`	Yes	Percentage weighting for the alternative. Must be greater than `0` and at most `100`. Decimal percentages are supported.
`transportOperation`	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.

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.

Selecting weighted modes as the transport type

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

{
  "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.

{
  "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.

Glasgow to Chișinău, with the London–Bucharest leg modelled as either standard `WATER` delivery (85%) or express `AIR` delivery (15%)

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.

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.

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.

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.

{
  "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"
          }
        }
      ]
    }
  ]
}

Vancouver to Toronto by diesel-electric train (70%), articulated truck (25%) and post-panamax container ship (5%)

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.

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.

Mode

Weights

Operations

Result

​Basic shape

​Properties

​Selecting weighted modes as the transport type

​What the percentages mean

​Same mode weighting

​Different mode weighting

Basic shape

Properties

Selecting weighted modes as the transport type

What the percentages mean

Same mode weighting

Different mode weighting