Skip to content

SIDRA ASSIGN

SIDRA ASSIGN is the lane-based traffic assignment feature of SIDRA INTERSECTION. From SIDRA INTERSECTION 11.0.4, the API can build its inputs and read its results. Your program can load O-D trip matrices from another model, create Assign Networks, process them and write O-D, route and convergence results to your own reports.

You need SIDRA INTERSECTION 11.0.4 or later. The modelling itself is described in the SIDRA ASSIGN user guide.

What you can do

Task What your program can do Start from
Build the demand Create Assign Volume Bins, zones and O-D volume sets. Write trip volumes for each Movement Class, with growth rates. ISIAPIProject.AddAssignVolumeBinFolder
Make an Assign Network Create it from an existing Basic Network, link it to an Assign Volume Bin, and connect each zone to a leg. ISIAPINetworkFolder.AddAssignNetwork
Set up the assignment Choose the assignment method, iterations and tolerances, and the Assign Scenarios to run. Set Fixed Route shares on each route. ISIAPIAssignScheme.AssignSchemeParameter, ISIAPIAssignScheme.AddAssignSchemeDemandScenario, ISIAPIRouteMC
Read the results For each O-D pair, overall and by Movement Class: flow, degree of saturation, travel time, delay, stop rate, distance, speed, operating cost, fuel and emissions. Also the routes used, the flow on each, the Sites along each route, and the convergence history. ISIAPIAssignScheme.OutputAssignScheme
Record the source Give your program a name. The API stores it on every Site, Network, Site Volume Bin and Assign Volume Bin your program creates or changes. ISIAPI.SourceAppName

Before you start

  • A Basic Network to start from. AddAssignNetwork works on a clone of it, so the Basic Network itself is not changed.
  • At least one feasible route between each O-D pair, for every Movement Class that has O-D volumes.
  • The SIDRA ASSIGN limits: 50 zones per Assign Network, 8 Zone Connectors per zone (one per external leg), 20 Fixed Routes, 12 Movement Classes, and 50 O-D volume sets per Assign Volume Bin.

How the objects fit together

Two branches of the object model carry SIDRA ASSIGN:

  • The demand belongs to the Project: AssignVolumeBinFolders, then each Assign Volume Bin with its zones, Movement Classes and O-D volume sets. Each O-D volume set holds a trip matrix.
  • The Assign Network is an ISIAPINetwork with NetworkType 1. Its AssignScheme holds the assignment settings, the zones placed in the network and their connections, the Assign Scenarios, and the results.
Project: ISIAPIProject
  AssignVolumeBinFolders -> <AssignVolumeBinFolder>
    AssignVolumeBins -> <AssignVolumeBin>
      AssignVolumeMCs [Movement Class code]
      AssignZones
      AssignVolumeSets -> <AssignVolumeSet>
        AssignTripMatrix
          AssignTripMatrixZones -> AssignTripMatrixZoneMCs     (growth rates)
          AssignTripMatrixZoneODs [origin, destination]
            -> AssignTripMatrixZoneODMCs [Movement Class code]  (volumes)
  NetworkFolders -> <NetworkFolder>
    AddAssignNetwork(sourceNetwork, assignVolBin)
    Networks -> <Network>                  (NetworkType: 0 = Basic, 1 = Assign)
      Routes -> <Route> -> RouteMCs        (Fixed Route shares)
      AssignScheme
        AssignSchemeParameter              (method, iterations, tolerances)
        AssignSchemeZones -> AssignSchemeZoneConnections
        AssignSchemeDemandScenarios        (O-D volume set, Analyse flag)
        OutputAssignScheme
          OutputAssignDualityGapHistoryRecords, OutputAssignConvergeHistoryRecords
          OutputAssignODs [origin, destination]
            OutputAssignODPerformance -> OutputAssignODPerformanceMCs
            OutputAssignODRoutes -> OutputAssignODRouteNwSites, OutputAssignODRoutePerformance

The rest of the tree is on Object model.

Names in the user guide and in the API

The API names some SIDRA ASSIGN items differently from the user guide.

User guide API type or member
Basic Network, Assign Network ISIAPINetwork with NetworkType 0, 1
Assignment parameters ISIAPIAssignSchemeParameter
Assign Volume Bin, bin folder ISIAPIAssignVolumeBin, ISIAPIAssignVolumeBinFolder
Zone (in the bin), zone (placed in the network) ISIAPIAssignZone, ISIAPIAssignSchemeZone
Zone Connector ISIAPIAssignSchemeZoneConnection
O-D Volume set ISIAPIAssignVolumeSet
Trip Matrix ISIAPIAssignTripMatrix
Assign O-D Volume, Fixed O-D Volume AssignTripMatrixZoneODMC.Volume, .RouteVolume
Generation, Attraction and Furness growth FlowScaleGrowthRateApplyOption (1, 2, 3); GenerationGrowthRate, AttractionGrowthRate
Assign Scenario ISIAPIAssignSchemeDemandScenario
Initial Vehicle Volumes (Use Site Volumes) AssignSchemeDemandScenario.AddSiteVolumesAsBase
Travel Time Coefficient AssignSchemeParameter.SUEPerceptionFactor
Fixed Trip Proportion ISIAPIRouteMC.AssignRouteVolumeFactor
Trip Performance ISIAPIOutputAssignODPerformance(MC), ISIAPIOutputAssignODRoutePerformance(MC)
O-D Preset (picks the O-D pairs for a report) None needed. A program can read every O-D pair.

The workflow in six steps

  1. Create an Assign Volume Bin. Call ISIAPIProject.AddAssignVolumeBinFolder(name), then AddAssignVolumeBin(softwareSetup) on the folder. The examples use 1 = Standard Left.
  2. Add zones and choose Movement Classes. Call AddAssignZone() for each zone. Set IsIncluded on AssignVolumeMCs[code] for each class beyond Light and Heavy Vehicles.
  3. Add an O-D volume set and its volumes. Call AddAssignVolumeSet(), then set AssignTripMatrix.AssignTripMatrixZoneODs[origin, destination].AssignTripMatrixZoneODMCs[code].Volume. Growth rates are set on AssignTripMatrixZones.
  4. Create the Assign Network and connect the zones. Call ISIAPINetworkFolder.AddAssignNetwork(basicNetwork, bin). Place each zone with LayoutX and LayoutY, then call AddAssignSchemeZoneConnection(networkSite, legOrientation, zoneAzimuthAngle).
  5. Choose the scenario and method. The first Assign Scenario is created for you and uses the first O-D volume set. Add more with AddAssignSchemeDemandScenario(volumeSet) and set Analyse on the one to run. Set AssignSchemeParameter.AssignmentMethod: 1 = All-or-Nothing, 2 = Incremental, 3 = User Equilibrium, 4 = Stochastic User Equilibrium.
  6. Process and read. Call Process() on the Assign Network, then read AssignScheme.OutputAssignScheme.

Reading results

  • The run: Number_iterations, Loading_iterations, UE_iterations and Duality_gap on OutputAssignScheme. The convergence history is in OutputAssignConvergeHistoryRecords and OutputAssignDualityGapHistoryRecords.
  • Each O-D pair: OutputAssignODs[origin, destination], then OutputAssignODPerformance for all classes and OutputAssignODPerformanceMCs by class. Calc_exists is false for a pair with no assigned or fixed volume.
  • Each route: OutputAssignODRoutes, then OutputAssignODRoutePerformance and OutputAssignODRouteNwSites, the Sites along the route.

Units for the results are not yet given in the API reference. The examples print route flow in veh/h. AssignTest2's CSV files give the unit of each result in its column heading.

Things that catch people out

  • Add zones to the bin first. AddAssignNetwork creates the network's zones from the zones in the bin. A zone added to the bin later is added to the Assign Network automatically, but it is not connected to a leg. Connect it with AddAssignSchemeZoneConnection.
  • The first Assign Scenario uses the first O-D volume set in the bin. The examples add their O-D volume sets themselves. Add at least one before you create the Assign Network.
  • Zone connection angles face the network. The angle is the point on the zone's circle where the connection starts. In the examples, a zone to the west joins the West leg at 90°, a zone to the north joins the North leg at 180°, a zone to the east joins the East leg at 270°, and a zone to the south joins the South leg at 0°.
  • Leg orientation codes. 0 = South, 2 = East, 4 = North, 6 = West; the odd numbers are the diagonals.
  • Movement Class collections are indexed by class code, 1 = Light Vehicles to 12 = User Class 6, not by position.
  • Light Vehicles and Heavy Vehicles are always included in an Assign Volume Bin.
  • Two methods throw an exception instead of returning false. RemoveAssignZone throws an exception if the zone is connected to a Network Site, and RemoveAssignVolumeSet throws an exception if the set is linked to an Assign Scenario.
  • AssignScheme is only for Assign Networks (NetworkType = 1). On a Basic Network it is null (None in Python).
  • Fixed Route Assignment is not an AssignmentMethod value. It works alongside the chosen method. Fixed volumes go in AssignTripMatrixZoneODMC.RouteVolume, and each route's share in ISIAPIRouteMC.UseAssignRouteVolumeFactor and AssignRouteVolumeFactor.
  • CloseProject() and Close() both save the project. Use CloseProjectWithoutSaving() to close without saving, or work on a copy.
  • One zone per external leg. An external leg connects to one zone only, and a zone can connect to up to eight legs. To feed one leg from two zones, split the leg with a Y-junction Site, or split the leg directly. With a Y-junction, keep its lanes continuous, check speeds, and allow for the extra distance.
  • No route between zones. If Process() returns false, read ProcessingError and the Network's diagnostics. A common cause is an O-D pair with volume for a Movement Class that no route allows, such as Heavy Vehicles where the movements exclude them.
  • Site volumes as background traffic. To load each Site's own volumes first, as static background traffic, set AddSiteVolumesAsBase to true on the Assign Scenario. This is the Use Site Volumes option under Initial Vehicle Volumes. AssignTest2 sets it to false on the Assign Scenario it adds.

Workflow sketch (Python)

This sketch loads one O-D volume into a copy of an existing project, runs a User Equilibrium assignment and prints one travel time. It assumes the project's first Basic Network has two Sites: the first with an external West leg, the second with an external East leg, and a Light Vehicle route between them. Set up Python.NET first, as in Getting started.

from SIDRASolutions.SI.API import SIAPI

api = SIAPI()
api.SourceAppName = "O-D matrix loader"   # stored on what this script changes
# Open a copy of your project: Close() saves it.
if not api.OpenProject(r"C:\Models\Corridor copy.sipx"):
    raise RuntimeError(api.LastErrorMessage)
project = api.Project

# 1-3. Demand: a bin, two zones and one O-D volume set
folder = project.AddAssignVolumeBinFolder("Demand")
vbin = folder.AddAssignVolumeBin(1)          # 1 = Standard Left; match your project
for zone_id in ("A", "B"):
    zone = vbin.AddAssignZone()
    zone.ID = zone_id
volumes = vbin.AddAssignVolumeSet()
volumes.ID = "AM36"
volumes.Name = "2036 AM peak"
pairs = volumes.AssignTripMatrix.AssignTripMatrixZoneODs
pairs["A", "B"].AssignTripMatrixZoneODMCs[1].Volume = 420.0   # 1 = Light Vehicles

# 4. An Assign Network from the first Basic Network
nf = project.NetworkFolders[0]
net = nf.AddAssignNetwork(nf.Networks[0], vbin)
scheme = net.AssignScheme
site1, site2 = net.NetworkSites[0], net.NetworkSites[1]
zone_a, zone_b = scheme.AssignSchemeZones["A"], scheme.AssignSchemeZones["B"]
zone_a.LayoutX, zone_a.LayoutY = site1.LayoutX - 120.0, site1.LayoutY + 30.0
zone_b.LayoutX, zone_b.LayoutY = site2.LayoutX + 180.0, site2.LayoutY + 30.0
zone_a.AddAssignSchemeZoneConnection(site1, 6, 90.0)     # West leg
zone_b.AddAssignSchemeZoneConnection(site2, 2, 270.0)    # East leg

# 5. The first Assign Scenario uses the first O-D volume set. Pick the method.
scheme.AssignSchemeParameter.AssignmentMethod = 3       # User Equilibrium

# 6. Process and read
if net.Process():
    result = scheme.OutputAssignScheme
    print("Duality gap:", result.Duality_gap)
    perf = result.OutputAssignODs["A", "B"].OutputAssignODPerformance
    print("A to B average travel time:", perf.Travel_time_average)
else:
    print(net.ProcessingError)

api.Close()   # Close() saves the project

Samples

The 11.0.4 sample ZIP has two SIDRA ASSIGN examples, in C#, C++ and Python:

  • AssignTest1 creates two roundabouts, a Basic Network, an Assign Volume Bin with four zones, and an Assign Network. It processes the network and prints the iteration counts, the duality gap and, for one O-D pair, the flow and degree of saturation on each route.
  • AssignTest2 opens the supplied project APIAssignTest2.sipx and adds an Assign Volume Bin with three zones and three O-D volume sets. It creates an Assign Network, adds a second Assign Scenario, sets the assignment method, runs each Assign Scenario in turn, and writes five CSV files to Projects: O-D results and routes, each overall and by Movement Class, and the convergence history.

See the Sample project guide for how to run them.