epymorph.log.movement

Capturing extremely detailed movement data from a simulation, which can be useful for debugging movement models.

MovementData

Bases: Protocol

Container for collected simulation movement data. Run the simulation inside a movement_data context and an instance of this class will be returned. After the simulation has completed, you can use this object to retrieve movement data either by clause or in aggregate across all clauses.

A note about axis ordering: both requested and actual data are NxN in shape, where N is the number of geo nodes in the simulation. We use the convention that the first axis represents where the movement is "from" and the second axis represents where the movement is "to". Movement due to the return clause is treated the same way: returning from work to home for example is recorded as (work, home).

requested_by abstractmethod

requested_by(clause: str) -> NDArray[SimDType]

Retrieve the time series (steps) of requested movement by clause.

Parameters:

• clause (str) –

  The clause to fetch.

Returns:

• NDArray[SimDType] –

  The movement data as a (S,N,N)-shaped array.

actual_by abstractmethod

actual_by(clause: str) -> NDArray[SimDType]

Retrieve the time series (steps) of actual movement by clause.

Parameters:

• clause (str) –

  The clause to fetch.

Returns:

• NDArray[SimDType] –

  The movement data as a (S,N,N,C)-shaped array.

requested_all abstractmethod

requested_all() -> NDArray[SimDType]

Retrieve the time series (steps) of requested movement for all clauses.

Returns:

• NDArray[SimDType] –

  The movement data as a (S,N,N)-shaped array.

actual_all abstractmethod

actual_all() -> NDArray[SimDType]

Retrieve the time series (steps) of actual movement for all clauses.

Returns:

• NDArray[SimDType] –

  The movement data as a (S,N,N,C)-shaped array.

movement_data

movement_data() -> Generator[MovementData, None, None]

Run one simulation in this context manager in order to capture detailed movement data. This returns a MovementData object which can be used -- after the context exits -- to retrieve the movement data.

Yields:

• MovementData –

  The object that will contain the collected movement data.

Examples:

with movement_data() as my_data:
    # don't access `my_data` yet, it hasn't recorded anything!
    sim = BasicSimulator(rume)
    my_results = sim.run()

# now you can use `my_data`
total_movement = my_data.actual_all()