common

ae_util

calculate_capacities(capacities: ndarray, layouts: ndarray) → ndarray
fill_project(project: ProjectWrapper, demand_nodes: PointEntity, demand_links: VirtualLinkEntity, transport_nodes: PointEntity, transport_segments: TransportSegmentEntity)
get_capacities_from_attribute(capacity_attribute: UniformAttribute, layout_attribute: UniformAttribute | None = None) → ndarray
get_cargo_allowed_from_attribute(cargo_allowed_attribute: UniformAttribute) → ndarray
get_demand_nodes(demand_nodes: PointEntity, point_generator: PointGenerator) → NodeCollection
get_max_speeds_from_attribute(max_speed_attribute: UniformAttribute) → ndarray
get_nodes(nodes: PointEntity, point_generator: PointGenerator) → NodeCollection
get_transport_directions(segments: TransportSegmentEntity) → ndarray

attributes

csv_tape

class BaseTapefile(timeline_info: TimelineInfo | None = None)

Bases: object

get_data(key: str)
get_next_timestamp() → Moment | None
has_update()
proceed_to(moment: Moment)
set_timeline(seconds: ndarray)
class CsvTape(timeline_info: TimelineInfo | None = None)

Bases: BaseTapefile

assert_parameter(parameter_name)
get_data(key: str) → float
initialize(csv: DataFrame, time_column: str = 'seconds')

entity_groups

class GeometryEntity(name: str = None)

Bases: EntityGroup

attributes: t.Dict[str, attribute.AttributeField] = {'reference': <movici_simulation_core.core.attribute.AttributeField object>}
dimensions()
ensure_ready() → None
get_geometry(slice=None) → Geometry
get_single_geometry(index: int) → BaseGeometry
is_ready()
reference
class GridCellEntity(name: str = None)

Bases: GeometryEntity

attributes: t.Dict[str, attribute.AttributeField] = {'grid_points': <movici_simulation_core.core.attribute.AttributeField object>}
get_geometry(slice=None) → ClosedPolygonGeometry
get_single_geometry(index: int) → Polygon
grid_points
is_ready()
points: PointEntity | None = None
set_points(points: PointEntity)
class LineEntity(name: str = None)

Bases: GeometryEntity

attributes: t.Dict[str, attribute.AttributeField] = {'_linestring2d': <movici_simulation_core.core.attribute.AttributeField object>, '_linestring3d': <movici_simulation_core.core.attribute.AttributeField object>}
dimensions()
get_geometry(slice=None) → LinestringGeometry
get_single_geometry(index: int) → LineString
is_ready() → bool
property linestring: CSRAttribute
class LinkEntity(name: str = None)

Bases: LineEntity

attributes: t.Dict[str, attribute.AttributeField] = {'from_node_id': <movici_simulation_core.core.attribute.AttributeField object>, 'to_node_id': <movici_simulation_core.core.attribute.AttributeField object>}
from_node_id
to_node_id
class PointEntity(name: str = None)

Bases: GeometryEntity

attributes: t.Dict[str, attribute.AttributeField] = {'x': <movici_simulation_core.core.attribute.AttributeField object>, 'y': <movici_simulation_core.core.attribute.AttributeField object>, 'z': <movici_simulation_core.core.attribute.AttributeField object>}
dimensions()
get_geometry(slice=None) → PointGeometry
get_single_geometry(index: int) → Point
is_ready()
x
y
z
class PolygonEntity(name: str = None)

Bases: GeometryEntity

attributes: t.Dict[str, attribute.AttributeField] = {'_polygon2d': <movici_simulation_core.core.attribute.AttributeField object>, '_polygon3d': <movici_simulation_core.core.attribute.AttributeField object>, '_polygon_legacy': <movici_simulation_core.core.attribute.AttributeField object>}
dimensions()
get_geometry(slice=None) → ClosedPolygonGeometry
get_single_geometry(index: int) → Polygon
is_ready() → bool
property polygon: CSRAttribute
class TransportLinkEntity(name: str = None)

Bases: LinkEntity

attributes: t.Dict[str, attribute.AttributeField] = {'layout': <movici_simulation_core.core.attribute.AttributeField object>}
layout
class TransportSegmentEntity(name: str = None)

Bases: LinkEntity

attributes: t.Dict[str, attribute.AttributeField] = {'_max_speed': <movici_simulation_core.core.attribute.AttributeField object>, 'capacity': <movici_simulation_core.core.attribute.AttributeField object>, 'layout': <movici_simulation_core.core.attribute.AttributeField object>}
capacity
layout
property max_speed
class VirtualLinkEntity(name: str = None)

Bases: LinkEntity

attributes: t.Dict[str, attribute.AttributeField] = {'capacity': <movici_simulation_core.core.attribute.AttributeField object>, 'max_speed': <movici_simulation_core.core.attribute.AttributeField object>}
capacity
max_speed
delayed_raise(err: Exception)

model_util

find_y_in_x(x: ndarray, y: ndarray)

find position of y in x, adapted from https://stackoverflow.com/a/8251757

get_transport_info(model_config: Dict[str, List[str] | None]) → Tuple[str, str]
safe_divide(numerator, denominator, fill_value=None)
try_get_geometry_type(geometry_type)

network

class Graph(indices: ndarray, indptr: ndarray, cost_factor_indices: ndarray)

Bases: object

Internal class that acts as an interface to scipy.sparse.csr_matrix() and scipy.sparse.csgraph.shortest_path() to be used by a Network. The arguments indices and indptr have the same meaining as in scipy.sparse.csr_matrix().

The graph is initially setup with a cost factor of 1, but a cost factor can be set using the update_cost_factor() method.

Rather than instantiating this class directly, it is recommended to use the Graph.from_network_data() constructor that will calculate the correct sparse matrix from from_node_id and to_node_id data and a node Index

Parameters:

  • indices – sparse matrix column indices array (see scipy.sparse.csr_matrix)

  • indptr – sparse matrix index pointer array (see scipy.sparse.csr_matrix)

  • cost_factor_indices – a mapping between position of a link in the transport link entity group and their position in the sparse matrix

cost_factor: ndarray
cost_factor_indices: ndarray
static from_network_data(node_idx: Index, from_node_id, to_node_id)

Create a Graph from Network data.

Parameters:

  • node_idx – the Index with all node ids

  • from_node_id – an array with source node id for every edge/link

  • to_node_id – an array with target node id for every edge/link

Returns:

a Graph representing the network

get_cost(source_idx, target_idx)

Helper method to retrieve the cost from a source to a target. Useful for testing.

Parameters:

  • source_idx – The index of the source node in the graph

  • target_idx – The index of the target node in the graph

get_neighbours(source_index)
indices: ndarray
indptr: ndarray
node_count: int
set_node_outgoing_cost_factor(node_idx, value)

Set the outgoing cost factor for all edges of a single node. Useful for enabling/disabling a virtual node by setting a very low or high value

shortest_path(indices: int | ndarray[tuple[Any, ...], dtype[int64]])
shortest_path_sum(predecessors, source_idx, target_indices, values, no_path_found=-1)
shortest_path_weighted_average(predecessors, source_idx, target_indices, values, weights=None, no_path_found=-1)
update_cost_factor(cost_factor: ndarray)

Set the cost factor of the graph.

Parameters:

cost_factor – a np.ndarray containing the cost factor of the links as they were provided to the Graph.from_network_data() constructor.

class Network(transport_nodes: PointEntity, transport_links: TransportSegmentEntity, virtual_nodes: PointEntity, virtual_links: LinkEntity, cost_factor: ndarray | None = None)

Bases: object

Representation of a transport network containing transport nodes and -links and virtual nodes and -links.

Transport nodes and -links represent the real network, and can have a cost factor. Virtual nodes and -links are special. They represent virtual entry/exit points to the network. Regular nodes cannot be used as entry/exit points.

If a regular node needs to be used as an entry/exit point, it must be connected to a virtual node, using a virtual link.

MAX_COST_FACTOR = inf
MIN_COST_FACTOR = 1e-12
all_node_index: Index
all_shortest_paths(virtual_node_ids: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None)

Compute the shortest path distance between all virtual nodes

all_shortest_paths_sum(values, virtual_node_ids=None, no_path_found=-1)

Calculate the sum of a quantity that is defined for every link on the shortest path from all source (virtual) nodes to all target (virtual) nodes. When the source node and the target node are the same, the summed value equals 0

Parameters:

  • values – an array (or array-like) with the quantity values on transport links that are to be summed

  • no_path_found – A fill value for when no valid shortest path can be found between source and target.

all_shortest_paths_weighted_average(values, virtual_node_ids=None, weights=None, no_path_found=-1)

Calculate the weighted average of a quantity that is defined for every link on the shortest path from all source (virtual) nodes to all target (virtual) nodes. The average is weighted by the cost factor of every link on the shortest path

Parameters:

  • values – an array (or array-like) with the quantity values on transport links that are to be averaged

  • virtual_node_ids – an array (or array-like) for which virtual nodes to calculate the weighted averages

  • weights – (optional) an array with alternative weights to calculate the weighted average. By default the network cost factor is used for both calculating the shortest path and as weights for the weighted average. Supplying this attributes makes it possible to calculate the shortest path by cost factor (eg. travel time) and the weighted average by a different attribute (eg. length). This array should have the same length as the cost_factor array

  • no_path_found – A fill value for when no valid shortest path can be found between source and target. This is also used for when the source and target node are the same

property cost_factor
get_shortest_path(source_node_id: int) → tuple[ndarray, ndarray]

see https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csgraph.shortest_path.html for more information.

:returns a (dist, prev) tuple

graph: Graph
initialize_cost_factor()
classmethod register_required_attributes(state: TrackedState, dataset_name: str, transport_segments_name: str, entities: Dict[str, EntityGroup | Type[EntityGroup]] | None = None) → NetworkEntities

Register the required entity groups for setting up a Network to the state.

By default it will register PointEntity for transport nodes as "transport_node_entities" and for virtual nodes as "virtual_node_entities", LinkEntity for virtual links as "virtual_link_entities" and TransportLinkEntity for transport links/segments. Transport links do not have a default name and this name must be given as the transport_segments_name argument. To override defaults, you can supply the entities argument

Parameters:

  • state – The TrackedState object to register the entity groups to

  • dataset_name – The dataset name for the entity groups

  • transport_segment_name – The name of the transport segment entities. Eg. for a road network this may be "road_segment_entities"

  • entities – A partial NetworkEntities dictionary to override the default registered entity groups. Keys in this dictionary may be "transport_nodes", "transport_links",``”virtual_nodes”`` and "virtual_links" and values must be either subclasses of Entity with the appropriate attributes or instances of these subclasses.

Returns:

A full NetworkEntities dictionary that can be used for the initialization of a Network

set_source_node(source_node_id: int)

Set the current source node for a shortest path calculation, this must be a virtual node id

shortest_path_sum(source_node_id, values, no_path_found=-1, values_are_mapped=False)

Calculate the sum of a quantity that is defined for every link on the shortest path from a source node to all target (virtual) nodes. When the source node and the target node are the same, the summed value equals 0

Parameters:

  • source_node_id – The entity id of the source (virtual) node

  • values – See Network.all_shortest_paths_weighted_average

  • no_path_found – See Network.all_shortest_paths_weighted_average

  • values_are_mapped – A boolean indicating whether the value array is in their original order or already mapped to the corresponding link index in the graph (default: False). This is usually False

shortest_path_weighted_average(source_node_id, values, weights=None, no_path_found=-1, values_are_mapped=False)

Calculate the weighted average of a quantity that is defined for every link on the shortest path from a source node to all target (virtual) nodes. The average is weighted by the cost factor of every link on the shortest path

Parameters:

  • source_node_id – The entity id of the source (virtual) node

  • values – See Network.all_shortest_paths_weighted_average

  • weights – See Network.all_shortest_paths_weighted_average

  • no_path_found – See Network.all_shortest_paths_weighted_average

  • values_are_mapped – A boolean indicating whether the value array is in their original order or already mapped to the corresponding link index in the graph (default: False). This is usually False

source_node_idx = None
tl_count = 0
tl_from_node_id: ndarray
tl_mapping: ndarray
tl_to_node_id: ndarray
transport_node_ids: ndarray
update_cost_factor(cost_factor: ndarray)

Update the cost factor of the network graph with a new cost factor for every transport link in the network, not including virtual links. The position of entries in the cost factor array is equal to the position of entities in the "transport_link" array used to construct this Network

Parameters:

cost_factor – An np.ndarray with the new cost factors

virtual_node_ids: ndarray
virtual_node_index: Index
vl_cost_factor: ndarray
vl_count = 0
vl_from_node_id: ndarray
vl_to_node_id: ndarray
class NetworkEntities

Bases: TypedDict

transport_nodes: PointEntity
virtual_nodes: PointEntity

return the indices of all links in a csr sparse network going from from_idx to to_idx

A graph may have multiple links between two nodes that each have a cost. This function finds the index of the link with the lowest cost between the from_idx and the to_idx node

in case there are no links connecting the nodes, this function return -1

time_series

class TimeSeries(iterable: Iterable[Tuple[int, T]] = ())

Bases: list, List[Tuple[int, T]]

property next_time
pop_until(timestamp: int) → Iterable[Tuple[int, T]]
sort()

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

Module contents

class CsvTape(timeline_info: TimelineInfo | None = None)

Bases: BaseTapefile

assert_parameter(parameter_name)
get_data(key: str) → float
initialize(csv: DataFrame, time_column: str = 'seconds')
class Graph(indices: ndarray, indptr: ndarray, cost_factor_indices: ndarray)

Bases: object

Internal class that acts as an interface to scipy.sparse.csr_matrix() and scipy.sparse.csgraph.shortest_path() to be used by a Network. The arguments indices and indptr have the same meaining as in scipy.sparse.csr_matrix().

The graph is initially setup with a cost factor of 1, but a cost factor can be set using the update_cost_factor() method.

Rather than instantiating this class directly, it is recommended to use the Graph.from_network_data() constructor that will calculate the correct sparse matrix from from_node_id and to_node_id data and a node Index

Parameters:

  • indices – sparse matrix column indices array (see scipy.sparse.csr_matrix)

  • indptr – sparse matrix index pointer array (see scipy.sparse.csr_matrix)

  • cost_factor_indices – a mapping between position of a link in the transport link entity group and their position in the sparse matrix

cost_factor: ndarray
cost_factor_indices: ndarray
static from_network_data(node_idx: Index, from_node_id, to_node_id)

Create a Graph from Network data.

Parameters:

  • node_idx – the Index with all node ids

  • from_node_id – an array with source node id for every edge/link

  • to_node_id – an array with target node id for every edge/link

Returns:

a Graph representing the network

get_cost(source_idx, target_idx)

Helper method to retrieve the cost from a source to a target. Useful for testing.

Parameters:

  • source_idx – The index of the source node in the graph

  • target_idx – The index of the target node in the graph

get_neighbours(source_index)
indices: ndarray
indptr: ndarray
node_count: int
set_node_outgoing_cost_factor(node_idx, value)

Set the outgoing cost factor for all edges of a single node. Useful for enabling/disabling a virtual node by setting a very low or high value

shortest_path(indices: int | ndarray[tuple[Any, ...], dtype[int64]])
shortest_path_sum(predecessors, source_idx, target_indices, values, no_path_found=-1)
shortest_path_weighted_average(predecessors, source_idx, target_indices, values, weights=None, no_path_found=-1)
update_cost_factor(cost_factor: ndarray)

Set the cost factor of the graph.

Parameters:

cost_factor – a np.ndarray containing the cost factor of the links as they were provided to the Graph.from_network_data() constructor.

class Network(transport_nodes: PointEntity, transport_links: TransportSegmentEntity, virtual_nodes: PointEntity, virtual_links: LinkEntity, cost_factor: ndarray | None = None)

Bases: object

Representation of a transport network containing transport nodes and -links and virtual nodes and -links.

Transport nodes and -links represent the real network, and can have a cost factor. Virtual nodes and -links are special. They represent virtual entry/exit points to the network. Regular nodes cannot be used as entry/exit points.

If a regular node needs to be used as an entry/exit point, it must be connected to a virtual node, using a virtual link.

MAX_COST_FACTOR = inf
MIN_COST_FACTOR = 1e-12
all_node_index: Index
all_shortest_paths(virtual_node_ids: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None)

Compute the shortest path distance between all virtual nodes

all_shortest_paths_sum(values, virtual_node_ids=None, no_path_found=-1)

Calculate the sum of a quantity that is defined for every link on the shortest path from all source (virtual) nodes to all target (virtual) nodes. When the source node and the target node are the same, the summed value equals 0

Parameters:

  • values – an array (or array-like) with the quantity values on transport links that are to be summed

  • no_path_found – A fill value for when no valid shortest path can be found between source and target.

all_shortest_paths_weighted_average(values, virtual_node_ids=None, weights=None, no_path_found=-1)

Calculate the weighted average of a quantity that is defined for every link on the shortest path from all source (virtual) nodes to all target (virtual) nodes. The average is weighted by the cost factor of every link on the shortest path

Parameters:

  • values – an array (or array-like) with the quantity values on transport links that are to be averaged

  • virtual_node_ids – an array (or array-like) for which virtual nodes to calculate the weighted averages

  • weights – (optional) an array with alternative weights to calculate the weighted average. By default the network cost factor is used for both calculating the shortest path and as weights for the weighted average. Supplying this attributes makes it possible to calculate the shortest path by cost factor (eg. travel time) and the weighted average by a different attribute (eg. length). This array should have the same length as the cost_factor array

  • no_path_found – A fill value for when no valid shortest path can be found between source and target. This is also used for when the source and target node are the same

property cost_factor
get_shortest_path(source_node_id: int) → tuple[ndarray, ndarray]

see https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csgraph.shortest_path.html for more information.

:returns a (dist, prev) tuple

graph: Graph
initialize_cost_factor()
classmethod register_required_attributes(state: TrackedState, dataset_name: str, transport_segments_name: str, entities: Dict[str, EntityGroup | Type[EntityGroup]] | None = None) → NetworkEntities

Register the required entity groups for setting up a Network to the state.

By default it will register PointEntity for transport nodes as "transport_node_entities" and for virtual nodes as "virtual_node_entities", LinkEntity for virtual links as "virtual_link_entities" and TransportLinkEntity for transport links/segments. Transport links do not have a default name and this name must be given as the transport_segments_name argument. To override defaults, you can supply the entities argument

Parameters:

  • state – The TrackedState object to register the entity groups to

  • dataset_name – The dataset name for the entity groups

  • transport_segment_name – The name of the transport segment entities. Eg. for a road network this may be "road_segment_entities"

  • entities – A partial NetworkEntities dictionary to override the default registered entity groups. Keys in this dictionary may be "transport_nodes", "transport_links",``”virtual_nodes”`` and "virtual_links" and values must be either subclasses of Entity with the appropriate attributes or instances of these subclasses.

Returns:

A full NetworkEntities dictionary that can be used for the initialization of a Network

set_source_node(source_node_id: int)

Set the current source node for a shortest path calculation, this must be a virtual node id

shortest_path_sum(source_node_id, values, no_path_found=-1, values_are_mapped=False)

Calculate the sum of a quantity that is defined for every link on the shortest path from a source node to all target (virtual) nodes. When the source node and the target node are the same, the summed value equals 0

Parameters:

  • source_node_id – The entity id of the source (virtual) node

  • values – See Network.all_shortest_paths_weighted_average

  • no_path_found – See Network.all_shortest_paths_weighted_average

  • values_are_mapped – A boolean indicating whether the value array is in their original order or already mapped to the corresponding link index in the graph (default: False). This is usually False

shortest_path_weighted_average(source_node_id, values, weights=None, no_path_found=-1, values_are_mapped=False)

Calculate the weighted average of a quantity that is defined for every link on the shortest path from a source node to all target (virtual) nodes. The average is weighted by the cost factor of every link on the shortest path

Parameters:

  • source_node_id – The entity id of the source (virtual) node

  • values – See Network.all_shortest_paths_weighted_average

  • weights – See Network.all_shortest_paths_weighted_average

  • no_path_found – See Network.all_shortest_paths_weighted_average

  • values_are_mapped – A boolean indicating whether the value array is in their original order or already mapped to the corresponding link index in the graph (default: False). This is usually False

source_node_idx = None
tl_count = 0
tl_from_node_id: ndarray
tl_mapping: ndarray
tl_to_node_id: ndarray
transport_node_ids: ndarray
update_cost_factor(cost_factor: ndarray)

Update the cost factor of the network graph with a new cost factor for every transport link in the network, not including virtual links. The position of entries in the cost factor array is equal to the position of entities in the "transport_link" array used to construct this Network

Parameters:

cost_factor – An np.ndarray with the new cost factors

virtual_node_ids: ndarray
virtual_node_index: Index
vl_cost_factor: ndarray
vl_count = 0
vl_from_node_id: ndarray
vl_to_node_id: ndarray
class TimeSeries(iterable: Iterable[Tuple[int, T]] = ())

Bases: list, List[Tuple[int, T]]

property next_time
pop_until(timestamp: int) → Iterable[Tuple[int, T]]
sort()

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

find_y_in_x(x: ndarray, y: ndarray)

find position of y in x, adapted from https://stackoverflow.com/a/8251757

get_transport_info(model_config: Dict[str, List[str] | None]) → Tuple[str, str]
safe_divide(numerator, denominator, fill_value=None)
try_get_geometry_type(geometry_type)