impedance_matrix - ObjectVision/GeoDMS GitHub Wiki

Network functions > Impedance functions > impedance_matrix

syntax

impedance_matrix(
   options,
   link_imp,
   link_f1,
   link_f2,
   startPoint_node_rel,
   startPoint_org_rel,     // optional, depending on options
   endPoint_node_rel,
   endPoint_dst_rel,       // optional, depending on options
   ...                     // additional optional arguments
)

description

The impedance_matrix function calculates shortest path impedances between multiple origin zones and multiple destination zones using Dijkstra's algorithm. It produces an origin-destination (OD) matrix as output.

Unlike impedance_table which treats all start points as a single origin, impedance_matrix supports multiple distinct origin zones, enabling full OD matrix calculations.

The function uses a highly optimized parallel implementation that processes each origin zone independently across multiple CPU cores.

arguments

required arguments

argument domain values description
options void String Configuration string specifying output options (see Impedance options)
link_imp Link Float32/Float64 Impedance (cost/distance/time) for each link
link_f1 Link Node "From" node for each link
link_f2 Link Node "To" node for each link
startPoint_node_rel StartPoint Node Node where each start point connects to the network
endPoint_node_rel EndPoint Node Node where each end point connects to the network

optional arguments (depending on options)

argument domain values description
startPoint_org_rel StartPoint OrgZone Origin zone for each start point (required for multiple origins)
endPoint_dst_rel EndPoint DstZone Destination zone for each end point
startPoint_imp StartPoint Float32/Float64 Additional impedance at start points
endPoint_imp EndPoint Float32/Float64 Additional impedance at end points
max_imp void Float32/Float64 Maximum impedance cutoff
od_max_imp OrgZone×DstZone Float32/Float64 OD-specific maximum impedance

conditions

  1. All Link attributes must have the same domain (Link unit).
  2. The values unit of link_f1 and link_f2 must be the same (Node unit).
  3. startPoint_node_rel values must be valid node indices or null.
  4. endPoint_node_rel values must be valid node indices or null.
  5. link_imp values must be non-negative (negative impedances cause undefined behavior).
  6. Null values in link_imp are treated as impassable links.

result

The function returns a unit<uint32> representing the set of OD pairs, with subitems depending on the options:

subitem type description
org_rel OD→OrgZone Origin zone for each OD pair
dst_rel OD→DstZone Destination zone for each OD pair
impedance OD→Float64 Shortest path impedance for each OD pair
od_org_node OD→Node Entry node for each OD pair (if requested)
od_dst_node OD→Node Exit node for each OD pair (if requested)
alt_imp OD→Float64 Alternative impedance sum (if requested)
link_attr OD→Float64 Link attribute sum along path (if requested)

performance

aspect indication
time complexity O(O × (E + N log N)) where O = origins, E = edges, N = nodes
memory O(N + E + O × D) where D = destinations per origin
parallelization fully parallel - each origin processed on separate thread

performance tips

  1. Use max_imp to limit search radius and reduce computation
  2. Use sparse result mode for large networks with few connections per origin
  3. Consider using impedance_matrix_od64 for more than 2³² OD pairs
  4. For grid-based problems, consider griddist instead

example

// Define network
unit<uint32> Node: nrofrows = 1000;
unit<uint32> Link: nrofrows = 3000
{
   attribute<Node>    f1;        // from node
   attribute<Node>    f2;        // to node  
   attribute<float32> impedance; // travel time in minutes
}

// Define zones
unit<uint32> OrgZone: nrofrows = 50;
unit<uint32> DstZone: nrofrows = 100;

// Define connection points
unit<uint32> StartPoint: nrofrows = 50
{
   attribute<Node>    node_rel;    // nearest network node
   attribute<OrgZone> org_rel;     // which origin zone
}

unit<uint32> EndPoint: nrofrows = 100
{
   attribute<Node>    node_rel;    // nearest network node
   attribute<DstZone> dst_rel;     // which destination zone
}

// Calculate OD matrix
unit<uint32> OD := impedance_matrix(
   'bidirectional;startPoint(org_rel);endPoint(dst_rel);cut(OrgZone_max_imp)',
   Link/impedance,
   Link/f1,
   Link/f2,
   StartPoint/node_rel,
   StartPoint/org_rel,
   EndPoint/node_rel,
   EndPoint/dst_rel,
   60f                    // max 60 minutes
)
{
   attribute<OrgZone> org_rel;
   attribute<DstZone> dst_rel;
   attribute<float64> impedance;  // travel time in minutes
}

see also

GeoDMS ©Object Vision BV. Source code distributed under GNU GPL-3. Documentation distributed under CC BY-SA 4.0.

GeoDMS ©Object Vision BV. Source code distributed under GNU GPL-3. Documentation distributed under CC BY-SA 4.0.

⚠️ **GitHub.com Fallback** ⚠️