.. _api-documentation: .. py:module:: network_tester The Network Tester API ---------------------- The :py:class:`Experiment` Class ```````````````````````````````` .. autoclass:: Experiment() :members: __init__, new_core, new_flow, new_group, run, placements, allocations, routes, system_info, machine .. _experimental-parameters: Experimental Parameters ``````````````````````` Global Parameters ~~~~~~~~~~~~~~~~~ The following experimental parameters apply globally and cannot be overridden on a core-by-core or flow-by-flow basis. They can be changed between groups. .. attribute:: Experiment.timestep The timestep (in seconds) with which packets are generated by any packet generators in the experiment. Default value: 0.001 (i.e. 1 ms) All timing related parameters (e.g. :py:attr:`~Experiment.duration` and :py:attr:`~Experiment.record_interval`) are internally converted into multiples of this timestep and rounded to the nearest number of steps .. warning:: Setting this value too small will result in the traffic generator software being unable to meet timing deadlines and thus the experiment failing. In practice, 1.5 us is the smallest this can be set but larger values are required if any core is the source of many flows or if large numbers of metrics are being recorded. .. attribute:: Experiment.duration The duration (in seconds) to run the traffic generators and record results for each experimental group. Default value: 1.0 See also: :py:attr:`~Experiment.warmup`, :py:attr:`~Experiment.cooldown` and :py:attr:`Experiment.flush_time`. .. attribute:: Experiment.warmup The duration (in seconds) to run the traffic generators without recording results before beginning result recording for each experimental group. Default value: 0.0 Many experiments require the network to be in a stable state for their results to be meaningful. To achieve this, a warmup period can be specified during which time the network is allowed to settle into a stable state before any results are recorded. See also: :py:attr:`~Experiment.duration`, :py:attr:`~Experiment.cooldown` and :py:attr:`~Experiment.flush_time`. .. attribute:: Experiment.cooldown The duration (in seconds) to run the traffic generators without recording results after result recording is completed for each experimental group. Default value: 0.0 Since the clocks in individual SpiNNaker cores are not perfectly in sync (and can drift significantly during long-duration experimental groups), it may be necessary for traffic generators to continue producing traffic for a short time after their local timer indicates the end of the experiment in order to maintain consistent network load for any traffic generators which are still running. See also: :py:attr:`~Experiment.duration`, :py:attr:`~Experiment.warmup` and :py:attr:`~Experiment.flush_time`. .. attribute:: Experiment.flush_time The pause (in seconds) which is added between experimental groups to allow any packets which remain in the network to be drained. Default value: 0.01 This is especially important when :py:attr:`~Experiment.consume_packets` has been set to False. See also: :py:attr:`~Experiment.duration`, :py:attr:`~Experiment.warmup` and :py:attr:`~Experiment.cooldown`. .. attribute:: Experiment.record_interval The interval (in seconds) at which metrics are recorded during an experiment. Default value: 0.0 Special case: If zero, metrics will be recorded once at the end each group's execution. See :ref:`metric-recording` for the set of metrics which can be recorded. .. attribute:: Experiment.router_timeout Sets the router timeout (in router clock cycles at (usually) 133MHz). Default value: None (do not change) If set to an integer, this sets the number of clock cycles before a packet times out and is dropped. :py:meth:`Experiment.run` will throw a :py:exc:`ValueError` if the value presented is not a valid router timeout. Emergency routing will be disabled. If set to a tuple (wait1, wait2), wait1 sets the number of clock cycles before emergency routing is tried and wait2 gives the number of additional cycles before the packet is dropped. :py:meth:`Experiment.run` will throw a :py:exc:`ValueError` if the values presented are not valid router timeouts. If None, the timeout will be left as the default when the system was booted. If this field is set to anything other than None at any point during the experiment, a single core on every chip will be used to set the router timeout. This may result in new cores being created internally and placed on otherwise unused chips. .. attribute:: Experiment.reinject_packets Enable dropped packet reinjection. Default value: False (do not use dropped packet reinjection). Enabling this feature at any point during the experiment will cause core 1 to be reserved on *all* chips to perform packet reinjection. See also: :py:attr:`Experiment.record_reinjected`, :py:attr:`Experiment.record_reinject_overflow` and :py:attr:`Experiment.record_reinject_missed`. .. _flow-attributes: Flow/Traffic Generator Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following experimental parameters apply to each flow (and thus each traffic generator) in the experiment and control the pattern of packets generated and sent down each flow. The global default for each value can be set by setting the corresponding :py:class:`Experiment` attribute. The default for flows sourced by a particular core can be set by setting the corresponding :py:class:`Core` attribute. These values may also be overridden on a group-by-group basis. For example:: >>> e = Experiment(...) >>> c0 = e.new_core() >>> c1 = e.new_core() >>> c2 = e.new_core() >>> f0 = e.new_flow(c0, c1) >>> f1 = e.new_flow(c0, c3) >>> f2 = e.new_flow(c2, c3) >>> e.probability = 1.0 >>> c0.probability = 0.9 >>> f0.probability = 0.8 >>> # First group: f0, f1, f2 all have probability == 0.0 >>> with e.new_group(): ... e.probability = 0.0 ... c0.probability = 0.0 ... f0.probability = 0.0 >>> # Second group: f2 has probability == 0.1 but f0 and f1 have >>> # probabilities 0.9 and 0.8 respectively. >>> with e.new_group(): ... e.probability = 0.1 .. attribute:: Flow.probability Core.probability Experiment.probability The probability, between 0.0 and 1.0, of a packet being generated in a given timestep. Default value: 1.0 (Generate a packet every timestep.) Packet generation is also subject to the burst parameters :py:attr:`~Flow.burst_period`, :py:attr:`~Flow.burst_duty`, and :py:attr:`~Flow.burst_phase`. By default packets are only generated according to :py:attr:`~Flow.probability` since bursting behaviour is not enabled. .. attribute:: Flow.packets_per_timestep Core.packets_per_timestep Experiment.packets_per_timestep The number of packets to generate each timestep. Default value: 1 (Generate a single packet every timestep.) The probability of each packet being generated is independent and set to :py:attr:`Flow.probability`. .. attribute:: Flow.num_retries Core.num_retries Experiment.num_retries Number of times to re-try sending a packet if back-pressure from the network blocks it. Default value: 0 (Give up immediately when faced with back-pressure) .. attribute:: Flow.burst_period Flow.burst_duty Flow.burst_phase Core.burst_period Core.burst_duty Core.burst_phase Experiment.burst_period Experiment.burst_duty Experiment.burst_phase Set the bursting behaviour of the traffic generated for a flow. Default values: :py:attr:`~Flow.burst_period` = 1.0, :py:attr:`~Flow.burst_duty` = 0.0 and :py:attr:`~Flow.burst_phase` = 0.0. (Not bursting). If :py:attr:`~Flow.burst_period` is 0.0, packets will be generated each timestep with probability :py:attr:`~Flow.probability`. If :py:attr:`~Flow.burst_period` is set to a non-zero number of seconds, packets may only be generated the proportion of the time specified by :py:attr:`~Flow.burst_duty`, every :py:attr:`~Flow.burst_period` seconds. :: # # burst_period seconds # |------------------------------| # (burst_duty * burst_period) seconds # |-------| # (burst_phase * burst_period) seconds # |----| # . . # maybe send +----.--+ +----.--+ # | . | | . | # | . | | . | # never send ...---+ . +----------------------+ . +---... # . . # . . # time = t time = t + burst_period :py:attr:`~Flow.burst_phase` gives the initial phase of the bursting behaviour. Note that the phase is not reset at the start of each group. Values outside of the range 0.0 - 1.0 will be wrapped to within this range. Special case: If :py:attr:`~Flow.burst_phase` is set to None, the phase of the bursting behaviour will be chosen randomly. .. attribute:: Flow.use_payload Core.use_payload Experiment.use_payload Should a payload field be added to each generated packet? Default value: False (Generate 40-bit short packets) If True, 72-bit 'long' multicast packets are generated. If False, 40-bit 'short' packets are generated. .. _core-attributes: Core Parameters ~~~~~~~~~~~~~~~ The following experimental parameters apply to each core in the experiment. The global default for each value can be set by setting the corresponding :py:class:`Experiment` attribute. These values may also be overridden on a group-by-group basis. .. attribute:: Core.seed Experiment.seed The seed for the random number generator in the specified core or None to select a random seed automatically. Default value: None (Seed randomly automatically). If set to a non-None value, the seed is (re)set at the start of each group. .. attribute:: Core.consume_packets Experiment.consume_packets Should the specified core consume packets from the network? Default value: True (Consume packets from the network) If set to False, packets sent via any flow to the core will not be consumed from the network. This will cause the packets to back-up in the network and eventually cause routers to drop packets. See also :py:attr:`Experiment.flush_time`. .. _metric-recording: Metric Recording Selection `````````````````````````` The following boolean attributes control what metrics are recorded during an experiment. Note that the set of recorded metrics may not be changed during an experiment (though the recording interval can, see :py:attr:`Experiment.record_interval`). By default, no metrics are recorded. .. attribute:: Experiment.record_local_multicast Experiment.record_external_multicast Experiment.record_local_p2p Experiment.record_external_p2p Experiment.record_local_nearest_neighbour Experiment.record_external_nearest_neighbour Experiment.record_local_fixed_route Experiment.record_external_fixed_route Experiment.record_dropped_multicast Experiment.record_dropped_p2p Experiment.record_dropped_nearest_neighbour Experiment.record_dropped_fixed_route Experiment.record_counter12 Experiment.record_counter13 Experiment.record_counter14 Experiment.record_counter15 Record changes in each of the SpiNNaker router counter registers. If any of these metrics are recorded, a single core on every chip will be configured accordingly ensuring router counter values are recorded for all chips in the machine. This may result in new cores being created internally and placed on core 2 of otherwise unused chips. .. attribute:: Experiment.record_reinjected Experiment.record_reinject_overflow Experiment.record_reinject_missed Records droppped packet reinjection metrics. :py:attr:`Experiment.record_reinjected` The number of dropped packets which have been reinjected. :py:attr:`Experiment.record_reinject_overflow` The number of dropped packets which were not reinjected due to the packet reinjector's buffer being full. :py:attr:`Experiment.record_reinject_missed` A lower bound on the number of dropped packets which were not reinjected due to the packet reinjector being unable to collect them from the router in time. If any of these metrics are recorded, a single core on every chip will be configured accordingly ensuring router counter values are recorded for all chips in the machine. This may result in new cores being created internally and placed on core 2 of otherwise unused chips. Additionally, recording any of these values will cause a further core to be reserved on *all* chips to perform packet reinjection, even if it is not enabled by :py:attr:`Experiment.reinject_packets` at any point in the experiment. See also: :py:attr:`Experiment.reinject_packets`. .. attribute:: Experiment.record_sent Record the number of packets successfully sent for each flow. .. attribute:: Experiment.record_blocked Record the number of packets which could not be sent for each flow due to back-pressure from the network. Note that blocked packets are not resent. .. attribute:: Experiment.record_received Record the number of packets received at each sink of each flow. The :py:class:`Results` Class ````````````````````````````` .. autoclass:: Results() :members: .. autofunction:: to_csv The :py:class:`Core`, :py:class:`Flow` and :py:class:`Group` Classes ```````````````````````````````````````````````````````````````````` .. autoclass:: Core() :members: .. attribute:: name The human-readable name of this core. .. attribute:: chip The (x, y) coordinate of the chip this core should reside on. Alternatively may be set to None if the core should be placed automatically on a suitable chip when the experiment is run. .. autoclass:: Flow() :members: .. attribute:: name The human-readable name of this flow. .. attribute:: source The source core of the flow. .. attribute:: sinks A list of sink cores for the flow. .. attribute:: weight The weight placement & routing hint for the flow. .. autoclass:: Group() :members: .. attribute:: name The human-readable name of this group.