Core Contents
Component
Contains classes describing specific track components and behaviour.
- class spur.core.component.MultiBlockTrack(model, uid, num_tracks: int, num_blocks: int, traversal_time, jitter=<spur.core.jitter.NoJitter object>, collection=None)
A track component that can contain multiple signal blocks and tracks in parallel.
For each individual track inside the component, the train moves through the successive blocks using a Cellular Automaton setup. The traversal time through each block is the total component traversal time evenly divided by the number of blocks. After spending this duration of time, the train will move to the next block along its direction of travel whenever the next block is unoccupied.
This component assigns each train to a track by putting trains travelling in the same direction into the same track as close together as possible, in order to maximize the track utilization.
- accept_agent(agent: Agent)
Accept a request for an agent to use the component
Parameters
- agentAny child of BaseAgent class
The agent that is requesting use of the component.
- can_accept_agent(agent) bool
Check whether agent is eligible to use this component based on component and collection states.
If the component does not belong to a collection, returns True by default, meaning the decision to accept the agent’s request is purely based on resource capacity. Can be overriden in child classes to include custom logic.
If the component does belong to a collection, determine acceptance based on collection state by default. Can be overriden in child classes to include custom logic.
Parameters
- agentAny child of Agent class
The agent that is requesting use of the component.
Returns
- bool
Whether agent is eligible to use the component.
- class spur.core.component.MultiTrackStation(model, uid, num_stopping_tracks: int, num_bypass_tracks: int, bypass_time: int, dwell_c, dwell_d, dwell_loc, dwell_scale, jitter=<spur.core.jitter.NoJitter object>, collection=None)
With Burr dwell time distribution
- accept_agent(agent: Agent)
Accept a request for an agent to use the component
Parameters
- agentAny child of BaseAgent class
The agent that is requesting use of the component.
- can_accept_agent(agent: Agent) bool
Check whether agent is eligible to use this component based on component and collection states.
If the component does not belong to a collection, returns True by default, meaning the decision to accept the agent’s request is purely based on resource capacity. Can be overriden in child classes to include custom logic.
If the component does belong to a collection, determine acceptance based on collection state by default. Can be overriden in child classes to include custom logic.
Parameters
- agentAny child of Agent class
The agent that is requesting use of the component.
Returns
- bool
Whether agent is eligible to use the component.
- class spur.core.component.PhysicsTrack(model, uid, length, track_speed, jitter=<spur.core.jitter.NoJitter object>, collection=None)
A physics-based track component simulating train movement
This component uses properties of the agent using it to determine the length of time to traverse the object.
- WARNING: This component is not yet fully developed. Currently only
has a capcity of 1.
Attributes
- modelspur.core.model.Model
The model controller
- uidmixed
The unique component id
- lengthint
The track length, in model distance units
- track_speedint
The maximum track speed, in model distance units per model time step
- jitterspur.core.jitter.BaseJitter child, optional
The Jitter object used to perturb the base time. Defaults to NoJitter
Raises
- NotPositiveError
If the track length or speed are not strictly positive
- class spur.core.component.SimpleCrossover(model, uid, traversal_time, jitter=<spur.core.jitter.NoJitter object>, collection=None)
A simplified crossover track component.
This component acts as a ‘bottleneck’ track component with a capacity of 1. It is possible to extend the behaviour here to allow for directional passing or non-passing as needed.
Attributes
- modelspur.core.model.Model
The model controller
- uidmixed
The unique component id
- traversal_timeint
The number of time steps required to traverse the component
- jitterspur.core.jitter.BaseJitter child, optional
The Jitter object used to perturb the base time. Defaults to NoJitter
Raises
- NotPositiveError
If the traversal time is not strictly positive.
- class spur.core.component.SimpleStation(model, uid, mean_boarding, mean_alighting, jitter=<spur.core.jitter.NoJitter object>, collection=None)
Simple station components.
Simple stations use a linear combination of boarding and alighting times to calcualte dwell times at stations. Currently that model comes from San, H.P. and Mohd Masirin, M.I. (2016). Train Dwell Time Models for Rail Passenger Service
2 + 0.4 * boarding + 0.4 * alighting + jitter
SimpleStation components have a capacity of 1
Warning
The SimpleStation component is only reasonable if the simulation time is in seconds.
Attributes
- modelspur.core.model.Model
The model controller
- uidmixed
The unique component id
- mean_boardingint
The average number of passengers boarding the train at the station
- mean_alightingint
The average number of passengers alighting from the train at the station.
- jitterspur.core.jitter.BaseJitter child, optional
The Jitter object used to perturb the base time. Defaults to NoJitter
- class spur.core.component.SimpleYard(model, uid, capacity, jitter=<spur.core.jitter.NoJitter object>, collection=None)
A yard component with simple behaviour.
Yards act as sources or sinks of agents, and are the place where agents can be ‘spawned’ to enter the simulation. Agents placed in SimpleYard components are set as ready to attach to a new agent immediately.
Attributes
- modelspur.core.model.Model
The model controller
- uidmixed
The unique component id
- capcityint
The number of agents the component can handle
- jitterspur.core.jitter.BaseJitter child, optional
The Jitter object used to perturb the base time. Defaults to NoJitter
- class spur.core.component.TimedStation(model, uid, mean_boarding, mean_alighting, traversal_time, jitter=<spur.core.jitter.NoJitter object>, collection=None)
Timed station component.
A timed station simply waits for a specified set of time.
WARNING This component may not fully work, or may have been depreciated.
Attributes
- modelspur.core.model.Model
The model controller
- uidmixed
The unique component id
- mean_boardingint
The average number of passengers boarding the train at the station
- mean_alightingint
The average number of passengers alighting from the train at the station.
- jitterspur.core.jitter.BaseJitter child, optional
The Jitter object used to perturb the base time. Defaults to NoJitter
- class spur.core.component.TimedTrack(model, uid, traversal_time, capacity=1, jitter=<spur.core.jitter.NoJitter object>, collection=None)
A timed traversal component.
This component represents a track with a fixed traversal time. Traversal times can be perturbed by provided jitter.
Attributes
- modelspur.core.model.Model
The model controller
- uidmixed
The unique component id
- traversal_timeint
The baseline number of model steps to traverse the component
- capcityint
The number of agents the component can handlValueErrorime. Defaults to NoJitter
Exception
Jitter
Contains classes describing random perturbations known as jitter
- class spur.core.jitter.BaseJitter
Abstract jitter component for perturbations
Methods
- jitter()
Returns a perturbation value
- class spur.core.jitter.DisruptionJitter(p: float, delay: int)
Jitter component producing perturbations based on probabilistic disruptions
This Jitter checks a random number against a supplied probability valuee each each time jitter() is called. If the value is below the probability threshold, a specified perturbation is returned. Otherwise, no perturbation occurs.
Methods
- jitter()
Calculates and returns a perturbation value
Raises
- NotAProbabilityError
If the supplied probability is not between [0, 1]
- class spur.core.jitter.GaussianJitter(mean=0.0, std=1.0)
Jitter component producing Gaussian (normally) distributed perturbations
Methods
- jitter()
Calculates and returns a Gaussian distributed perturbation value
- class spur.core.jitter.LognormalJitter(mean=0.0, std=1.0)
Jitter component producing lognormally distributed perturbations
Methods
- jitter()
Calculates and returns a lognormally distributed perturbation value
- class spur.core.jitter.NoJitter
Jitter component that produces no jitter
NoJitter is used as a default non-perturbation setting for many components.
Methods
- jitter()
Returns a zero perturbation value
Model
Contains classes describing the model controller
- class spur.core.model.Model(*args, **kwargs)
The model class
Attributes
- GNetworkX.MultiGraph
The graph representation of the model system
- simLoglogging.Logger
The logging component of the model
- add_component(component_type, u, v, key, *args, **kwargs)
Add a component to the model network
Parameters
- component_typestr
The class name (e.g. SimpleStation of the component to add)
- ustr
The first node end of the component
- vstr
The second node end of the component
- keystr
The key of the component
- add_components_from_json_file(filepath)
Add a set of components from a formatted JSON file
Parameters
- filepathstr
The path to the JSON file containing components.
- add_components_from_list(components)
Add a list of components to the network
Parameters
- componentslist
The list of components to add
- add_routes_and_tours_from_json_files(routes_filepath, tours_filepath)
Add a set of routes and tours from JSON files
Parameters
- routes_filepathstr
The path to the routes JSON file
- tours_filepathstr
The path to the tours JSON file
- add_routes_and_tours_from_lists(routes, tours)
Add routes and tours to the model from lists
Parameters
- routeslist
A list of route objects
- tourslist
A list of tour objects
- add_train(uid, max_speed, tour) Train
Add a train to the model
Parameters
- uidmixed
Unique ID of the object
- max_speedint
The maximum speed of the train
- tourTour
The tour for the train to follow
Returns
- Train
The initialized and added train object
- add_trains_from_json_file(filepath)
Add a set of trains to the model from a formatted JSON file
Parameters
- filepathstr
The path to the JSON file
- add_trains_from_list(trains)
Add trains to the model from a list of train objects
Parameters
- trainslist
A list of train objects
- run(until=None)
Run the model for a specified time
Parameters
- untilint, optional
The number of steps to run the model for, by default None which runs until all components finished.
- start()
Start the model
Starting the model activates all agents and components to be ready for running.
Route
Contains classes describing routes and route behaviour.
- class spur.core.route.Route
A route object containing a set of components for an agent to traverse.
Attributes
- segmentslist
A list of RouteSegment objects to traverse in order
- append(component, arrival=None, departure=None)
Append a component to the current route. Specified arrival and departure times are used to hold trains to a schedule.
Parameters
- componentBaseComponent
The component to append to the route
- arrivalint, optional
The expected arrival at the component in simulation time, by default None
- departureint, optional
The permitted departure time from the component in simulation time, by default None
- property current_component
Get the current component of the route. If the route has ended, the component will be None.
- property current_segment
Get the current RouteSegment. If the route has ended, the component will be None.
- insert(component, idx, arrival=None, departure=None)
Insert a component to the current route. Specified arrival and departure times are used to hold trains to a schedule.
Parameters
- componentBaseComponent
The component to append to the route
- idxint
The location in the list to insert the component.
- arrivalint, optional
The expected arrival at the component in simulation time, by default None
- departureint, optional
The permitted departure time from the component in simulation time, by default None
- property next_component
Get the component following the current one. If this is the end of the route, the component will be None
- property next_segment
Get the RouteSegment following the current one. If this is the end of the route, the segment will be None.
- property previous_component
Get the previous segment component. If the route is at the start, the component will be None.
- property previous_segment
Get the previous RouteSegment. If the route is at the start, the segment will be None.
- reset()
Set the route pointer to the beginning of the route.
- traverse()
Traverse the list of segments
This method traverses through sequential RouteSegments and provides instruction to the agents.
Raises
- StopIteration
If the segments list is empty on traversal
- uids()
Get a list of all segment component unique IDs in the route.
- Returns:
list of uids for each component.
- Return type:
list
- class spur.core.route.RouteSegment(route, component, prev, next, arrival, departure)
A class containing information on specific route segments.
Attributes
- routespur.core.Route
The route the component is a part of
- componentspur.core.BaseComponent child
The component this route segment represents
- prevRouteSegment
The previous route segment
- nextRouteSegment
The next route segment
- arrivalint
The expected arrival at the route segment in simulation time
- departureint
The permitted departure time from the route segment in simulation time
Tour
Contains classes describing tours and tour behaviour.
- class spur.core.tour.Tour(creation_time, deletion_time)
A tour object containing a set of routes for an agent to traverse.
Attributes
- tour_segmentslist
A list of TourSegment objects to traverse in order
- append(route)
Append a route to the current tour.
Parameters
- routeRoute
The route to append to the tour
- insert(route, idx)
Insert a route to the current tour.
Parameters
- routeRoute
The route to append to the tour
- idxint
The location in the list to insert the route.
- traverse()
Traverse the list of tour segments
This method traverses through sequential TourSegments and their RouteSegments, and provides instruction to the agents.
It also merges the last segment of one route with the first of the next route (both of which should be the same).
Raises
- StopIteration
If the tour segments list is empty on traversal
- class spur.core.tour.TourSegment(tour, route, prev, next)
A class containing information on specific tour segments.
Attributes
- tourspur.core.Tour
The tour the route is a part of
- routespur.core.Route
The route this tour segment represents
- prevTourSegment
The previous tour segment
- nextTourSegment
The next tour segment
Train
- class spur.core.train.Train(model, uid, tour, max_speed)
A class used to represent a train agent
Attributes
- accelerationfloat
The acceleration of the train (WARNING: NOT USED OR REQURIED)
- decelerationfloat
The deceleration of the train (WARNING: NOT USED OR REQUIRED)
- tourTour
The tour of the train
- basic_traversal(distance, track_speed)
Perform a basic traversal of a cleared distance.
This method determines the final speed of a train at the end of a section of track by examining the next track section for occupancy. The method then calls get_basic_traversal_time to calculate the time taken to accelerate and decelerate and traverse the track.
WARNING: NOT CURRENTLY USED
- get_basic_traversal_time(distance, track_speed, final_speed)
WARNING: NOT IMPLEMENTED
- run()
The action method of the train agent.
Train agents run a simple and continuous process of moving through their prescribed tour, alternately requesting access to a component and then calling the do() method of the component to be processed. Agents can be interrupted from their current process and assigned a new tour before they start running again.