spinn_front_end_common.interface.provenance package

Submodules

spinn_front_end_common.interface.provenance.router_prov_mapper module

class spinn_front_end_common.interface.provenance.router_prov_mapper.Plotter(db_filename: str, verbose: bool = False)

Bases: ContextManager[SQLiteDB]

Code to plot provenance data from the database

Parameters:

• db_filename – The name of a file that contains (or will contain) an SQLite database holding the data.

• verbose – Flag to trigger print messages

cmap

get_per_chip_prov_details(info: str) → Tuple[str, int, int, ndarray]

Gets the provenance of a per chip basis

Parameters:

info – The name of the metadata to sum

Returns:

name, max x, max y and data

get_per_chip_prov_types() → FrozenSet[str]

Returns:

A set of the descriptions available at chip level

get_per_core_prov_types() → FrozenSet[str]

Returns:

A set of the descriptions available at core level

get_sum_chip_prov_details(info: str) → Tuple[str, int, int, ndarray]

Gets the sum of the provenance

Parameters:

info – The name of the metadata to sum

Returns:

name, max x, max y and data

plot_per_chip_data(key: str, output_filename: str) → None

Plots the metadata for this key/term to the file at a chip level

Parameters:

• key – The name of the metadata to plot, or a unique fragment of it

• output_filename

plot_per_core_data(key: str, output_filename: str) → None

Plots the metadata for this key/term to the file at a core level

Parameters:

• key – The name of the metadata to plot, or a unique fragment of it

• output_filename

spinn_front_end_common.interface.provenance.router_prov_mapper.main() → None

Generate heat maps from SpiNNaker provenance databases

Module contents

class spinn_front_end_common.interface.provenance.AbstractProvidesProvenanceDataFromMachine

Bases: object

Indicates that an object provides provenance data retrieved from the machine.

abstractmethod get_provenance_data_from_machine(placement: Placement) → None

Get provenance data items for a placement and store them in the provenance DB.

Parameters:

placement – the placement of the object

class spinn_front_end_common.interface.provenance.FecTimer(algorithm: str, work: TimerWork)

Bases: object

Timer.

Parameters:

• algorithm – Name of algorithm being timed

• work – Type of work being timed

APPLICATION_RUNNER = 'Application runner'

classmethod end_category(category: TimerCategory) → None

This method should only be called via the View!

Parameters:

category – Stage to end

error(reason: str) → None

Ends an algorithm timing and records that it failed.

Parameters:

reason – What caused the error

classmethod setup() → None

Starts the Timer and puts it into WAITING mode

Checks and saves cfg values so they don’t have to be read each time

skip(reason: str) → None

Records that the algorithms is being skipped and ends the timer.

Parameters:

reason – Why the algorithm is being skipped

skip_all_cfgs_false(pairs: List[Tuple[str, str]], reason: str) → bool

Skips if all Boolean cfg values are False.

If either cfg value is True this methods keep the timer running and returns False (did not skip).

If both cfg values are False this method records the reason, ends the timing and returns True (it skipped).

Typically called if the algorithm should run if either cfg values is set True.

Parameters:

• pairs – section, options pairs to check

• reason – Reason to record for the skip

Returns:

True if skip has been called

skip_if_cfg_false(section: str, option: str) → bool

Skips if a Boolean cfg values is False.

If this cfg value is True this methods keep the timer running and returns False (did not skip).

If the cfg value is False this method records the reason, ends the timing and returns True (it skipped).

Typically called if the algorithm should run if the cfg value is set True.

Parameters:

• section – Section level to be applied to both options

• option – The option to check

Returns:

True if skip has been called

skip_if_cfgs_false(section: str, option1: str, option2: str) → bool

Skips if two Boolean cfg values are both False.

If either cfg value is True this methods keep the timer running and returns False (did not skip).

If both cfg values are False this method records the reason, ends the timing and returns True (it skipped).

Typically called if the algorithm should run if either cfg values is set True.

Parameters:

• section – Section level to be applied to both options

• option1 – One of the options to check

• option2 – The other option to check

Returns:

True if skip has been called

skip_if_empty(value: bool | int | str | Sized | None, name: str) → bool

Skips if the value is one that evaluates to False.

If the value is considered True (if value) this methods keep the timer running and returns False (did not skip).

If the value is False this method records the reason, ends the timing and returns True (it skipped).

Parameters:

• value – Value to check if True

• name – Name to record for that value if skipping

Returns:

True if skip has been called

skip_if_has_not_run() → bool

Skips if the simulation has not run.

If the simulation has run used this methods keep the timer running and returns False (did not skip).

If there was no run this method records the reason, ends the timing and returns True (it skipped).

Currently not used as a better check is skip_if_empty on the data needed for the algorithm.

Returns:

True if skip has been called

skip_if_virtual_board() → bool

Skips if a virtual board is being used.

If a real board is being used this methods keep the timer running and returns False (did not skip).

If a virtual board is being used this method records the reason, ends the timing and returns True (it skipped).

Typically called for algorithms that require a real board to run.

Returns:

True if skip has been called

classmethod start_category(category: TimerCategory) → None

This method should only be called via the View!

Parameters:

category – category to switch to

classmethod stop_category_timing() → None

Stops all the timing.

Typically only called during simulator shutdown

class spinn_front_end_common.interface.provenance.GlobalProvenance(database_file: str | None = None, memory: bool = False)

Bases: SQLiteDB

Specific implementation of the Database for SQLite 3.

Note

Not thread safe on the same database file. Threads can access different DBs just fine.

Note

This totally relies on the way SQLite’s type affinities function. You can’t port to a different database engine without a lot of work.

Parameters:

• database_file – The name of a file that contains (or will contain) an SQLite database holding the data. If omitted, either the default file path or an unshared in-memory database will be used (suitable only for testing).

• memory – Flag to say unshared in-memory can be used. Otherwise a None file will mean the default should be used

get_category_timer_sum(category: TimerCategory, n_reset: int | None = None) → int

Get the total runtime for one category of algorithms

Parameters:

• category – What to get the sum of

• n_reset – Which reset to sum or None for all

Returns:

total off all run times with this category

classmethod get_global_provenace_path() → str

Get the path of the current provenance database of the last run

Used the cfg setting tpath_global_provenance placing this in the timestamp directory

Warning

Calling this method between start/reset and run may result in a path to a database not yet created.

Raises:

ValueError – if the system is in a state where path can’t be retrieved, for example before run is called

Returns:

Directory for this database based on the cfg setting

get_machine_on_by_reset(n_reset: int | None = None) → int

Get the total time the machine was on for this reset

Parameters:

n_reset

Returns:

get_run_time_of_buffer_extractor() → str

Gets the buffer extractor provenance item(s) from the last run

Returns:

A possibly multi line string with for each row which matches the LIKE %BufferExtractor

get_timer_provenance(algorithm: str) → str

Gets the timer provenance item(s) from the last run

Parameters:

algorithm – The value to LIKE search for in the algorithm column. Can be the full name, or have % and _ wildcards.

Returns:

A possibly multi line string with for each row which matches the like a line algorithm: value

get_timer_sum_by_algorithm(algorithm: str) → int

Get the total runtime for one algorithm

Parameters:

algorithm

Returns:

total off all run times with this algorithm

get_timer_sum_by_category(category: TimerCategory) → int

Get the total runtime for one category of algorithms

Parameters:

category

Returns:

total of all run times with this category

get_timer_sum_by_category_and_reset(category: TimerCategory, n_reset: int | None = None) → int

Get the total runtime for one category of algorithms

Returns:

total of all run times with this category

get_timer_sum_by_work(work: TimerWork) → int

Get the total runtime for one work type of algorithms

Parameters:

work

Returns:

total off all run times with this category

insert_category(category: TimerCategory, machine_on: bool) → int

Inserts category into the category_timer_provenance returning id

Parameters:

• category – Name of Category starting

• machine_on – If the machine was done during all or some of the time

Returns:

ID of the inserted category

insert_category_timing(category_id: int, delta: timedelta) → None

Inserts run time into the category

Parameters:

• category_id – id of the Category finished

• delta – Time to be recorded

insert_timing(category: int, algorithm: str, work: TimerWork, delta: timedelta, skip_reason: str | None) → None

Inserts algorithms run times into the timer_provenance table

Parameters:

• category – Category Id of the Algorithm

• algorithm – Algorithm name

• work – Type of work being done

• delta – Time to be recorded

• skip_reason – The reason the algorithm was skipped or None if it was not skipped

insert_version(description: str, the_value: str) → None

Inserts data into the version_provenance table

Parameters:

• description – The package for which the version applies

• the_value – The version to be recorded

retreive_log_messages(min_level: int = 0) → List[str]

Returns:

All log messages at or above the min_level

run_query(query: str, params: Iterable[str | int | float | None | bytes] = ()) → List[Row]

Opens a connection to the database, runs a query, extracts the results and closes the connection

The return type depends on the use_sqlite_rows parameter. By default this method returns tuples (lookup by index) but the advanced tuple type can be used instead, which supports lookup by name used in the query (use AS name in the query to set).

This method will not allow queries that change the database unless the read_only flag is set to False.

Note

This method is mainly provided as a support method for the later methods that return specific data. For new IntergationTests please add a specific method rather than call this directly.

Parameters:

• query – The SQL query to be run. May include ? wildcards

• params – The values to replace the ? wildcards with. The number and types must match what the query expects

Returns:

A list possibly empty of tuples/rows (one for each row in the database) where the number and type of the values corresponds to the where statement

store_log(level: int, message: str, timestamp: datetime | None = None) → None

Stores log messages into the database

class spinn_front_end_common.interface.provenance.LogStoreDB

Bases: LogStore

Log message storage mechanism that uses a database.

get_location() → str

Retrieves the location of the log store.

Returns:

Path to the database holding the log store.

retreive_log_messages(min_level: int = 0) → List[str]

Retrieves all log messages at or above the min_level.

Parameters:

min_level – Constraint on the minimum logging level to retrieve.

Returns:

A list of messages that satisfy the constraint.

store_log(level: int, message: str, timestamp: datetime | None = None) → None

Writes the log message for later retrieval.

Parameters:

• level – The logging level.

• message – The logged message.

• timestamp – The time-stamp of the message.

class spinn_front_end_common.interface.provenance.ProvenanceReader(provenance_data_path: str | None = None)

Bases: BaseDatabase

Provides a connection to a database containing provenance for the current run and some convenience methods for extracting provenance data from it.

By default this will wrap around the database used to store the provenance of the last run. The path is not updated so this reader is not effected by a reset or an end.

The assumption is that the database is in the current provenance format. This includes both that DDL statements used to create the database but also the underlying database structure (currently sqlite3)

Warning

This class is only a wrapper around the database file so if the file is deleted the class will no longer work.

Create a wrapper around the database.

The suggested way to call this is without the provenance_data_path parameter, allowing get_last_run_database_path() to find the correct path.

Parameters:

provenance_data_path – Path to the provenance database to wrap

cores_with_late_spikes() → List[Tuple[int, int, int, int]]

Gets the x, y, p and count of the cores where late spikes arrived.

Cores that received spikes but where none were late are not included.

Returns:

A list hopefully empty of tuples (x, y, p, count) of cores where their where late arriving spikes.

static demo() → None

A demonstration of how to use this class.

See also unittests/interface/provenance/test_provenance_database.py

get_cores_with_provenace() → List[Tuple[int, int, int]]

Gets the cores with provenance.

Returns:

A list tuples (x, y, p)

get_monitor_by_chip(description: str) → List[Tuple[int, int, str | int | float | bytes | None]]

Gets the monitor values for a specific item.

Parameters:

description

Returns:

list of tuples x, y, value)

get_provenance_for_router(x: int, y: int) → str

Gets the provenance item(s) from the last run relating to a chip.

Parameters:

• x – The X coordinate of the chip

• y – The Y coordinate of the chip

Returns:

A possibly multi-line string with for each row which matches the like a line description_name: value

get_router_by_chip(description: str) → List[Tuple[int, int, int]]

Gets the router values for a specific item.

Parameters:

description

Returns:

list of tuples (x, y, value)

messages() → List[str]

List all the provenance messages.

Returns:

all messages logged or not; order is whatever the DB chooses

run_query(query: str, params: Iterable[str | int | float | None | bytes] = ()) → List[Sequence[str | int | float | bytes | None]]

Opens a connection to the database, runs a query, extracts the results and closes the connection.

The return type depends on the use_sqlite_rows parameter. By default this method returns tuples (lookup by index) but the advanced tuple type can be used instead, which supports lookup by name used in the query (use AS name in the query to set).

This method will not allow queries that change the database unless the read_only flag is set to False.

Note

This method is mainly provided as a support method for the later methods that return specific data. For new IntergationTests please add a specific method rather than call this directly.

Parameters:

• query – The SQL query to be run. May include ? wildcards

• params – The values to replace the ? wildcards with. The number and types must match what the query expects

Returns:

A list possibly empty of tuples/rows (one for each row in the database) where the number and type of the values corresponds to the where statement

class spinn_front_end_common.interface.provenance.ProvenanceWriter(database_file: str | None = None)

Bases: BaseDatabase

Specific implementation of the Database for SQLite 3.

Note

Not thread safe on the same database file. Threads can access different DBs just fine.

Note

This totally relies on the way SQLite’s type affinities function. You can’t port to a different database engine without a lot of work.

Parameters:

database_file – The name of a file that contains (or will contain) an SQLite database holding the data. If omitted, either the default file path or an unshared in-memory database will be used (suitable only for testing).

insert_board_provenance(connections: Dict[Tuple[int, int], str] | None) → None

Write the connection details retrieved from spalloc_client job to the boards_provenance table.

Parameters:

connections – {(x, y): hostname, …} or None

insert_connector(pre_population: str, post_population: str, the_type: str, description: str, the_value: str | int | float | bytes | None) → None

Inserts edge data into the connector_provenance

Parameters:

• pre_population – Name of the pre-population / vertex

• post_population – Name of the post-population / vertex

• the_type – Class of the connector

• description – type of value

• the_value – data

insert_core(x: int, y: int, p: int, description: str, the_value: str | int | float | bytes | None) → None

Inserts data for a specific core into the core_provenance table.

Parameters:

• x – X coordinate of the chip

• y – Y coordinate of the chip

• p – ID of the core

• description – type of value

• the_value – data

insert_gatherer(x: int, y: int, address: int, bytes_read: int, run: int, description: str, the_value: str | int | float | bytes | None) → None

Records provenance into the gatherer_provenance table.

Parameters:

• x – X coordinate of the chip

• y – Y coordinate of the chip

• address – SDRAM address read from

• bytes_read – number of bytes read

• run – run number

• description – type of value

• the_value – data

insert_monitor(x: int, y: int, description: str, the_value: str | int | float | bytes | None) → None

Inserts data into the monitor_provenance table.

Will only save data is write_provance is on.

Parameters:

• x – X coordinate of the chip

• y – Y coordinate of the chip

• description – type of value

• the_value – data

insert_monitor_value(x: int, y: int, description: str, the_value: str | int | float | bytes | None) → None

Inserts data into the monitor_provenance table.

Always saves the data even if write_provence is off.

Parameters:

• x – X coordinate of the chip

• y – Y coordinate of the chip

• description – type of value

• the_value – data

insert_power(description: str, the_value: str | int | float | bytes | None) → None

Inserts a general power value into the power_provenance table.

Parameters:

• description – Type of value

• the_value – data

insert_report(message: str) → None

Save and if applicable logs a message to the reports table.

Only logs the messages up to the cut-off set by configuration provenance_report_cutoff

Parameters:

message

insert_router(x: int, y: int, description: str, the_value: int, expected: bool = True) → None

Inserts data into the router_provenance table.

Parameters:

• x – X coordinate of the chip

• y – Y coordinate of the chip

• description – type of value

• the_value – data

• expected – Flag to say this data was expected

class spinn_front_end_common.interface.provenance.ProvidesProvenanceDataFromMachineImpl

Bases: AbstractProvidesProvenanceDataFromMachine

An implementation that gets provenance data from a region of integers on the machine.

N_SYSTEM_PROVENANCE_WORDS = 6

get_provenance_data_from_machine(placement: Placement) → None

Retrieve the provenance data.

Parameters:

placement – Which vertex are we retrieving from, and where was it

classmethod get_provenance_data_size(n_additional_data_items: int) → int

Parameters:

n_additional_data_items

Returns:

Size of the provenance data to read

parse_extra_provenance_items(label: str, x: int, y: int, p: int, provenance_data: Sequence[int]) → None

Convert the remaining provenance words (those not in the standard set) into provenance items.

Called by get_provenance_data_from_machine()

Parameters:

• label – A descriptive label for the vertex (derived from label and placed position) to be used for provenance error reporting to the user.

• x – x coordinate of the chip where this core

• y – y coordinate of the core where this core

• p – virtual id of the core

• provenance_data – The list of words of raw provenance data.

parse_system_provenance_items(label: str, x: int, y: int, p: int, provenance_data: Sequence[int]) → None

Given some words of provenance data, convert the portion of them that describes the system provenance into proper provenance items.

Called by get_provenance_data_from_machine()

Parameters:

• label – A descriptive label for the vertex (derived from label and placed position) to be used for provenance error reporting to the user.

• x – x coordinate of the chip where this core

• y – y coordinate of the core where this core

• p – virtual id of the core

• provenance_data

reserve_provenance_data_region(spec: DataSpecificationGenerator) → None

Insert command to reserve a memory region.

Parameters:

spec – The data specification being written.

class spinn_front_end_common.interface.provenance.TimerCategory(value)

Bases: Enum

Different Categories a FecTimer can be in

Parameters:

• value – Enum ID

• category_name – Name to use when describing this category

DATA_SPEC_LOAD = 4

DATA_SPEC_OTHER = 3

DATA_SPEC_SYNAPSE = 5

EXTRACT_DATA = 11

MACHINE_OFF = 7

MACHINE_ON = 6

MAPPING = 8

RESETTING = 12

RUN_LOOP = 10

RUN_OTHER = 9

SETTING_UP = 2

SHUTTING_DOWN = 13

WAITING = 1

property category_name: str

The category name as passed into the init.

class spinn_front_end_common.interface.provenance.TimerWork(value)

Bases: Enum

Different Work types an Algorithm could be doing

Parameters:

• value – Enum ID

• work_name – Descriptor for this Enum

COMPRESSING = 5

CONTROL = 6

EXTRACTING = 9

EXTRACT_DATA = 10

GET_MACHINE = 2

LOADING = 3

LOADING_DATA = 4

OTHER = 1

REPORT = 11

RUNNING = 8

SYNAPSE = 7

property work_name: str

The name for this timer distinction.