spinn_front_end_common.interface.provenance package

Module contents

class spinn_front_end_common.interface.provenance.AbstractProvidesLocalProvenanceData

Bases: object

Indicates an object that provides locally obtained provenance data.

GraphProvenanceGatherer will check all Vertices and all Edges in the ApplicationGraph

get_local_provenance_data()

Get an iterable of provenance data items.

Return type:iterable

class spinn_front_end_common.interface.provenance.FecTimer(algorithm, work)

Bases: object

APPLICATION_RUNNER = 'Application runner'

classmethod end_category(category)

This method should only be called via the View!

Parameters:category (SimulatorStage) – Stage to end

error(reason)

classmethod setup(simulator)

skip(reason)

skip_if_cfg_false(section, option)

skip_if_cfgs_false(section, option1, option2)

skip_if_empty(value, name)

skip_if_has_not_run()

skip_if_virtual_board()

classmethod start_category(category, machine_on=None)

This method should only be called via the View!

Parameters:

• category (TimerCategory) – category to switch to
• machine_on (None or bool) – What to change machine on too. Or None to leave as is

classmethod stop_category_timing()

class spinn_front_end_common.interface.provenance.GlobalProvenance(database_file=None, memory=False)

Bases: spinn_front_end_common.utilities.sqlite_db.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 (str or None) – 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 (bool) – 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)

Get the total runtime for one category of algorithms

Parameters:category (TimerCategory) – Returns:total off all runtimes with this category Return type:int

get_category_timer_sums(category)

Get the runtime for one category of algorithms split machine on, machine off

Parameters:category (TimerCategory) – Returns:total on and off time of instances with this category Return type:int

classmethod get_global_provenace_path()

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

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

get_run_time_of_BufferExtractor()

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

Returns:A possibly multiline string with for each row which matches the like %BufferExtractor description_name: value Return type:str

get_run_times()

Gets the algorithm running times from the last run. If an algorithm is invoked multiple times in the run, its times are summed.

Returns:A possibly multiline string with for each row which matches the like a line description_name: time. The times are in seconds. Return type:str

get_timer_provenance(algorithm)

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

Parameters:algorithm (str) – The value to LIKE search for in the algorithm column. Can be the full name, or have % and _ wildcards. Returns:A possibly multiline string with for each row which matches the like a line algorithm: value Return type:str

get_timer_sum_by_algorithm(algorithm)

Get the total runtime for one algorithm

Parameters:algorithm (str) – Returns:total off all runtimes with this algorithm Return type:int

get_timer_sum_by_category(category)

Get the total runtime for one category of algorithms

Parameters:category (TimerCategory) – Returns:total off all runtimes with this category Return type:int

get_timer_sum_by_work(work)

Get the total runtime for one work type of algorithms

Parameters:work (TimerWork) – Returns:total off all runtimes with this category Return type:int

insert_category(category, machine_on)

Inserts category into the category_timer_provenance returning id

Parameters:

• category (TimerCategory) – Name of Category starting
• machine_on (bool) – If the machine was done during all or some of the time

insert_category_timing(category_id, timedelta)

Inserts run time into the category

Parameters:

• category_id (int) – id of the Category finished
• timedelta (timedelta) – Time to be recorded

insert_timing(category, algorithm, work, timedelta, skip_reason)

Inserts algorithms run times into the timer_provenance table

Parameters:

• category (int) – Category Id of the Algorithm
• algorithm (str) – Algorithm name
• work (TimerWork) – Type of work being done
• timedelta (timedelta) – Time to be recorded
• skip_reason (str or None) – The reason the algorithm was skipped or None if it was not skipped

insert_version(description, the_value)

Inserts data into the version_provenance table

Parameters:

• description (str) – The package for which the version applies
• the_value (str) – The version to be recorded

retreive_log_messages(min_level=0)

Retrieves all log messages at or above the min_level

Parameters:min_level (int) – Return type:list(tuple(int, str))

run_query(query, params=())

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 param. 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 (str) – The SQL query to be run. May include ? wildcards
• or int) params (Iterable(str) – The values to replace the ? wildcards with. The number and types must match what the query expects
• read_only (bool) – see get_database_handle()
• use_sqlite_rows (bool) – see get_database_handle()

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

Return type:

list(tuple or Row)

store_log(level, message, timestamp=None)

Stores log messages into the database

Parameters:

• level (int) –
• message (str) –

class spinn_front_end_common.interface.provenance.AbstractProvidesProvenanceDataFromMachine

Bases: object

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

get_provenance_data_from_machine(placement)

Get an iterable of provenance data items.

Parameters:placement (Placement) – the placement of the object Return type:iterable

class spinn_front_end_common.interface.provenance.LogStoreDB

Bases: spinn_utilities.log_store.LogStore

get_location()

Retrieves the location of the log store.

Return type:str

retreive_log_messages(min_level=0)

Retrieves all log messages at or above the min_level.

Parameters:min_level (int) – Constraint on the minimum logging level to retrieve. Returns:A list of messages that satisfy the constraint. Return type:list(tuple(int, str))

store_log(level, message, timestamp=None)

Writes the log message for later retrieval.

Parameters:

• level (int) – The logging level.
• message (str) – The logged message.
• timestamp (datatime or None) – The timestamp of the message.

class spinn_front_end_common.interface.provenance.ProvenanceReader(provenance_data_path=None)

Bases: spinn_front_end_common.utilities.base_database.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 (None or str) – Path to the provenance database to wrap

cores_with_late_spikes()

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. Return type:list(tuple(int, int, int, int))

static demo()

A demonstration of how to use this class.

See also unittests/interface/provenance/test_provenance_database.py

get_cores_with_provenace()

Gets the cores with provenance.

Returns:A list tuples (x, y, p) Return type:list(tuple(int, int, int))

classmethod get_last_run_database_path()

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

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

get_monitor_by_chip(description)

Gets the monitor values for a specific item.

Parameters:description (str) – Returns:list of tuples x, y, value) Return type:lits((int, int float))

get_provenance_for_router(x, y)

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

Parameters:

• x (int) – The X coordinate of the chip
• y (int) – The Y coordinate of the chip

Returns:

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

Return type:

str

get_router_by_chip(description)

Gets the router values for a specific item.

Parameters:description (str) – Returns:list of tuples x, y, value) Return type:lits((int, int float))

messages()

List all the provenance messages.

Returns:all messages logged or not Return type:list(str)

run_query(query, params=())

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 param. 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 (str) – The SQL query to be run. May include ? wildcards
• or int) params (Iterable(str) – The values to replace the ? wildcards with. The number and types must match what the query expects
• read_only (bool) – see get_database_handle()
• use_sqlite_rows (bool) – see get_database_handle()

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

Return type:

list(tuple or Row)

class spinn_front_end_common.interface.provenance.ProvenanceWriter(database_file=None)

Bases: spinn_front_end_common.utilities.base_database.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 (str or None) – 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 (bool) – Flag to say unshared in-memory can be used. Otherwise a None file will mean the default should be used

insert_board_provenance(connections)

Write the conection treived from spalloc job

Parameters:connections (dict((int, int): str) or None) – {(x, y): hostname, …} or None

insert_connector(pre_population, post_population, the_type, description, the_value)

Inserts edge data into the connector_provenance

Parameters:

• pre_population (str) – Name of the pre population / vertex
• post_population (str) – Name of the post population / vertex
• the_type (str) – Class of the connector
• description (str) – type of value
• the_value (int) – data

insert_core(x, y, p, description, the_value)

Inserts data for a specific core into the core_provenance table

Parameters:

• x (int) – X coordinate of the chip
• y (int) – Y coordinate of the chip
• p (int) – id of the core
• description (str) – type of value
• the_value (int) – data

insert_gatherer(x, y, address, bytes_read, run, description, the_value)

Records provenance into the gatherer_provenance

Parameters:

• x (int) – X coordinate of the chip
• y (int) – Y coordinate of the chip
• address (int) – sdram address read from
• bytes_read (int) – number of bytes read
• run (int) – run number
• description (str) – type of value
• the_value (float) – data

insert_monitor(x, y, description, the_value)

Inserts data into the monitor_provenance table

Parameters:

• x (int) – X coordinate of the chip
• y (int) – Y coordinate of the chip
• description (str) – type of value
• the_value (int) – data

insert_power(description, the_value)

Inserts a general power value into the power_provenane table

Parameters:

• description (str) – Type of value
• the_value (float) – data

insert_report(message)

Save and if applicable logs a message to the report_table

Only logs the messages up to the cutoff set by cfg provenance_report_cutoff

Parameters:message (str) –

insert_router(x, y, description, the_value, expected=True)

Inserts data into the router provenance table

Parameters:

• x (int) – X coordinate of the chip
• y (int) – Y coordinate of the chip
• description (str) – type of value
• the_value (float) – data
• expected (bool) – Flag to say this data was expected

class spinn_front_end_common.interface.provenance.ProvidesProvenanceDataFromMachineImpl

Bases: spinn_front_end_common.interface.provenance.abstract_provides_provenance_data_from_machine.AbstractProvidesProvenanceDataFromMachine

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

N_SYSTEM_PROVENANCE_WORDS = 6

class PROVENANCE_DATA_ENTRIES

Bases: enum.Enum

Entries for the provenance data generated by models using provides provenance vertex.

CALLBACK_QUEUE_OVERLOADED = 1

The counter of the number of times the callback queue was overloaded

DMA_QUEUE_OVERLOADED = 2

The counter of the number of times the DMA queue was overloaded

MAX_NUMBER_OF_TIMER_TIC_OVERRUN = 5

The counter of the number of times the timer tick overran

TIMER_TIC_HAS_OVERRUN = 4

Whether the timer tick has overrun at all at any point

TRANSMISSION_EVENT_OVERFLOW = 0

The counter of transmission overflows

USER_QUEUE_OVERLOADED = 3

The counter of the number of times the user event queue overloaded

get_provenance_data_from_machine(placement)

Retrieve the provenance data.

Parameters:placement (Placement) – Which vertex are we retrieving from, and where was it

classmethod get_provenance_data_size(n_additional_data_items)

Parameters:n_additional_data_items (int) – Return type:int

parse_extra_provenance_items(label, x, y, p, provenance_data)

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

Called by get_provenance_data_from_machine()

Parameters:

• label (str) – A descriptive label for the vertex (derived from label and placed position) to be used for provenance error reporting to the user.
• x (int) – x coordinate of the chip where this core
• y (int) – y coordinate of the core where this core
• p (int) – virtual id of the core
• provenance_data (list(int)) – The list of words of raw provenance data.

parse_system_provenance_items(label, x, y, p, provenance_data)

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 (str) – A descriptive label for the vertex (derived from label and placed position) to be used for provenance error reporting to the user.
• x (int) – x coordinate of the chip where this core
• y (int) – y coordinate of the core where this core
• p (int) – virtual id of the core
• provenance_data (list(int)) –

reserve_provenance_data_region(spec)

Parameters:spec (DataSpecificationGenerator) – The data specification being written.

class spinn_front_end_common.interface.provenance.TimerCategory

Bases: enum.Enum

Different Categories a FecTimer can be in

DATA_GENERATION = <enum.auto object>

GET_MACHINE = <enum.auto object>

LOADING = <enum.auto object>

MAPPING = <enum.auto object>

RESETTING = <enum.auto object>

RUN_LOOP = <enum.auto object>

RUN_OTHER = <enum.auto object>

SETTING_UP = <enum.auto object>

SHUTTING_DOWN = <enum.auto object>

WAITING = <enum.auto object>

category_name

class spinn_front_end_common.interface.provenance.TimerWork

Bases: enum.Enum

Different Work types an Algorithm could be doing

BITFIELD = <enum.auto object>

COMPRESSING = <enum.auto object>

CONTROL = <enum.auto object>

EXTRACTING = <enum.auto object>

EXTRACT_DATA = <enum.auto object>

GET_MACHINE = <enum.auto object>

LOADING = <enum.auto object>

OTHER = <enum.auto object>

REPORT = <enum.auto object>

RUNNING = <enum.auto object>

SYNAPSE = <enum.auto object>

work_name