spinn_utilities.data package

Submodules

spinn_utilities.data.reset_status module

class spinn_utilities.data.reset_status.ResetStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different states the reset could be in.

This class is design to used internally by UtilsDataView.

HARD_RESET = 4

HAS_RUN = 2

NOT_SETUP = 0

SETUP = 1

SOFT_RESET = 3

spinn_utilities.data.run_status module

class spinn_utilities.data.run_status.RunStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different states the run could be in.

This is from the perspective of the users script. It says nothing about if there is C code running, i.e., has a sim.run (or similar) call started but not yet returned.

This is combined with the ResetStatus to get the needed status.

This class is design to used internally by UtilsDataView.

IN_RUN = 2

NOT_RUNNING = 1

NOT_SETUP = 0

SHUTDOWN = 5

STOPPING = 4

STOP_REQUESTED = 3

spinn_utilities.data.utils_data_writer module

class spinn_utilities.data.utils_data_writer.UtilsDataWriter(state: DataStatus)

Bases: UtilsDataView

Writer class for the information in UtilsDataView

This and subclass Writers are specifically designed to be used by the simulators (ASB) and unit tests only! Any other usage is not supported.

The Writers are specifically designed to support only one instant (typically held by ASB as self._data_writer).

Creating a new instant of the Writer will clear out any data added by the previous instance.

Unit tests can create a writer by doing …Writer.mock() or Writer.setup(). The mock method adds some default data such as directories and a Virtual 8 * 8 Machine, as well as allowing some back-door methods. …Writer.mock() is the recommended one for unit tests; setup() is more like what ASB does and allows for state changes such as writer.start_running.

ASB __init__() (or it subclasses) will create a new writer so a call to sim.setup will clear all previously held data.

Warning

As the Writers are not designed for general usage the methods can change without notice.

Parameters:

state (DataStatus) – State writer should be in

finish_run() → None

Puts all data into the state expected after sim.run ends.

get_report_dir_path() → str

Returns path to existing reports directory.

This is the high level directory which in which timestamp directories and run directories are placed.

As it is only accessed to create timestamp directories and remove old reports, this is not a view method.

Return type:

str

Raises:

SpiNNUtilsException – If the simulation_time_step is currently unavailable

hard_reset() → None

Puts all data back into the state expected at graph changed and sim.reset.

This resets any data set after sim.setup has finished.

classmethod mock() → Self

Creates a writer in mock mode.

All previous data will be cleared.

This should set the most likely defaults values. But be aware that what is considered the most likely default could change over time.

Unit tests that depend on any valid value being set should be able to depend on Mock.

A unit test that depends on a specific value should call mock() and then set that value.

Returns:

A Data Writer

Return type:

UtilsDataWriter

request_stop() → None

Used to indicate a user has requested a stop.

This is expected to be called during run from a different thread.

set_report_dir_path(reports_dir_path: str)

Checks and sets the reports_dir_path.

Parameters:

reports_dir_path (str)

Raises:

InvalidDirectory – if the reports_dir_path is not a directory

set_run_dir_path(run_dir_path: str)

Checks and sets the run_dir_path.

Parameters:

run_dir_path (str)

Raises:

InvalidDirectory – if the run_dir_path is not a directory

classmethod setup() → Self

Creates a writer in normal mode.

All previous data will be cleared

Returns:

A Data Writer

Return type:

UtilsDataWriter

shut_down() → None

Puts all data into the state expected after sim.end.

Most methods that change data, or state will raise an exception after this call.

Most data however will still be available.

soft_reset() → None

Puts all data back into the state expected at sim.reset but where the graph has not changed.

start_run() → None

Puts all data into the state expected after do_run_loop started.

stopping() → None

Puts all data into the state expected during stop.

Raises:

• SimulatorNotSetupException – If called before sim.setup

• SimulatorShutdownException – If called after sim.end

Module contents

class spinn_utilities.data.DataStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Different states the Data can be in.

This class is designed to used internally by UtilsDataView

MOCKED = 1

The system is (to be) setup in mocked mode for unit testing.

NOT_SETUP = 0

No setup calls have been done yet.

SETUP = 2

The system is (to be) setup for running user code.

SHUTDOWN = 3

The system has been shut down.

exception(data) → SpiNNUtilsException

Returns an instance of the most suitable data-not-available exception.

Parameters:

data – Parameter to pass to the relevant constructor.

Return type:

SpiNNUtilsException

class spinn_utilities.data.UtilsDataView

Bases: object

A read only view of the data available at each level.

Note

The state model of this class is designed primarily to support sPyNNaker.

All methods are class methods so can be accessed directly without instantiating a view. There is a stack of subclasses such as MachineDataView, FecDataView, SpynnakerDataView (and more). All inherit all methods. We reserve the right to override methods defined in one View in subclasses.

There are also Writer classes which override the Views but these are specifically designed to only be usable in unit tests and by the simulator (ASB) directly.

You should use the data view most appropriate to what you are doing i.e. If you are accessing it from a class or function in FEC, use FecDataView but if you are accessing it from sPyNNaker, use SpynnakerDataView. This will ensure that any changes to the view local to the code will affect all code in that package

The objects accessed this way should not be changed or added to. Changing or adding to any object accessed is unsupported as bypasses any check or updates done in the writer(s). Objects returned could be changed to immutable versions without notice!

The get… methods will either return a valid value or raise an exception if the data is currently not available. The get methods will will not return None unless specifically documented to do so. As a reasonable effort is made the setters to verify the data types, the get methods can be expected to return the correct type.

There are also several semantic sugar get… methods. Some are slightly faster but many are just to make the code more readable. Some semantic sugar methods do not start with get to keep the same name as the existing function on the object has.

The iterate… methods offer a view over the collections within mutable data objects, particularly ones changed between runs. There is no guarantee if the returned iterator will or will not reflect any changes to the underlying data object, nor that how a method behaves in this way does not change over time. So the methods should be called for every iteration.

Each iterate… method will have a corresponding get_n… which you need to do instead of len(iterate…) as we reserve the right to make any iterate… method return an iterable which does not support len without notice.

add… methods allow for the scripts directly or indirectly to add extra values. They allow the view to add extra safety such as type checking. They will raise an exception if called while the simulator is running.

The has… methods will return True if the value is known and False if not. Semantically they are the same as checking if the get raises an exception. They may be faster if the object needs to be generated on the fly or protected to be made immutable. has… methods have been added where found needed. More can easily be added if required.

The is… methods will return a Boolean value to say the simulator is in the expected state. They may throw an exception if called at an unexpected time. For example if called before sim.setup or after sim.end.

While how and where the underpinning DataModel(s) store data can change without notice, methods in View classes can be considered a supported API.

classmethod check_user_can_act() → None

Checks if the status is such that users can be making calls.

This does not error in the Mocked state

Raises:

• SimulatorRunningException – If sim.run is currently running

• SimulatorNotSetupException – If called before sim.setup

• SimulatorShutdownException – If called after sim.end

classmethod check_valid_simulator() → None

Throws an error if there is no simulator.

Raises:

• SimulatorNotSetupException – If called before sim.setup

• SimulatorShutdownException – If called after sim.end

classmethod get_executable_finder() → ExecutableFinder

The ExcutableFinder object created at time code is imported.

Return type:

ExcutableFinder

classmethod get_executable_path(executable_name: str) → str

Finds an executable within the set of folders. The set of folders is searched sequentially and the first match is returned.

Syntactic sugar for get_executable_finder().get_executable_path()

Parameters:

executable_name (str) – The name of the executable to find

Returns:

The full path of the discovered executable

Return type:

str

Raises:

KeyError – If no executable was found in the set of folders

classmethod get_executable_paths(executable_names: str) → List[str]

Finds each executables within the set of folders.

The names are assumed to be comma separated The set of folders is searched sequentially and the first match for each name is returned.

Names not found are ignored and not added to the list.

Syntactic sugar for get_executable_finder().get_executable_paths()

Parameters:

executable_names (str) – The name of the executable to find. Assumed to be comma separated.

Returns:

The full path of the discovered executable, or None if no executable was found in the set of folders

Return type:

list(str)

classmethod get_requires_data_generation() → bool

Reports if data generation is required.

Set to True at the start and by any change that could require data generation or mapping Remains True during the first run after a data change Only set to False at the end of the first run

Return type:

bool

classmethod get_requires_mapping() → bool

Reports if mapping is required.

Set to True at the start and by any change that could require any mapping stage to be called Remains True during the first run after a requires mapping. Only set to False at the end of the first run

Return type:

bool

classmethod get_run_dir_path() → str

Returns the path to the directory that holds all the reports for run.

This will be the path used by the last run call or to be used by the next run if it has not yet been called.

Note

In unit test mode this returns a temporary directory shared by all path methods.

Return type:

str

Raises:

SpiNNUtilsException – If the run_dir_path is currently unavailable

classmethod is_hard_reset() → bool

Check if the system has been hard reset since the last run finished.

Warning

During the first run after reset this continues to return True!

Returns False after a reset that was considered soft.

Return type:

bool

classmethod is_no_stop_requested() → bool

Checks that a stop request has not been sent.

Return type:

bool

Raises:

NotImplementedError – If this is called from an unexpected state

classmethod is_ran_ever() → bool

Check if the simulation has run at least once, ignoring resets.

Return type:

bool

Raises:

NotImplementedError – If this is called from an unexpected state

classmethod is_ran_last() → bool

Checks if the simulation has run and not been reset.

Return type:

bool

Raises:

NotImplementedError – If this is called from an unexpected state

classmethod is_reset_last() → bool

Reports if sim.reset called since the last sim.run.

Unlike is_soft_reset() and is_hard_reset() this method return False during any sim.run.

It also returns False after a sim.stop or sim.end call starts

Return type:

bool

Raises:

NotImplementedError – If this is called from an unexpected state

classmethod is_running() → bool

Checks if there is currently a simulation running.

That is a call to run has started but not yet stopped.

Return type:

bool

classmethod is_setup() → bool

Checks to see if there is already a simulator.

Return type:

bool

Raises:

NotImplementedError – If this is called from an unexpected state

classmethod is_shutdown() → bool

Determines if simulator has already been shutdown.

This returns False in the Mocked state

Return type:

bool

classmethod is_soft_reset() → bool

Check if the system has been soft reset since the last run finished.

Warning

During the first run after reset this continues to return True!

Returns False after a reset that was considered hard.

Return type:

bool

classmethod is_stop_already_requested() → bool

Checks if there has already been a request stop.

Also checks the state is such that a stop request makes sense.

Returns:

True if the stop has already been requested or if the system is stopping or has already stopped False if the stop request makes sense.

Return type:

bool

Raises:

• NotImplementedError – If this is called from an unexpected state

• SpiNNUtilsException – If the stop_run was not expected in the current state.

classmethod is_user_mode() → bool

Determines if simulator is currently not running so user is accessing data.

This returns False in the Mocked state.

Return type:

bool

Raises:

NotImplementedError – If the data has not yet been set up or on an unexpected run_status

classmethod raise_skiptest(reason: str, parent: Exception | None = None) → None

Sets the status as shutdown and raises a SkipTest

Parameters:

• reason (str) – Message for the Skip

• parent (Exception or None) – Exception which triggered the skip if any

Raises:

SkipTest very time called

classmethod register_binary_search_path(search_path: str)

Register an additional binary search path for executables.

Syntactic sugar for get_executable_finder().add_path()

Parameters:

search_path (str) – absolute search path for binaries

classmethod set_requires_data_generation() → None

Sets requires_data_generation to True.

Only the end of a run can set it to False

classmethod set_requires_mapping() → None

Sets requires_mapping and requires_data_generation to True.

Only the end of a run can set it to False