Package uk.ac.manchester.spinnaker.machine

Class Machine

java.lang.Object
uk.ac.manchester.spinnaker.machine.Machine
All Implemented Interfaces:
Iterable<Chip>, MappableIterable<Chip>
Direct Known Subclasses:
VirtualMachine
public class Machine extends Object implements MappableIterable<Chip>
A representation of a SpiNNaker Machine with a number of Chips.

Machine is also iterable, providing the chips within the machine.

Author:
Christian-B
See Also:

  • Field Details

    • machineDimensions

      @Valid public final @Valid MachineDimensions machineDimensions
      Size of the machine along the X and Y axes, in chips.

    • boot

      @Valid public final @Valid ChipLocation boot
      The coordinates of the chip used to boot the machine.

    • version

      public final MachineVersion version
      The version of the machine based on its height and width.

  • Constructor Details

    • Machine

      public Machine(MachineDimensions machineDimensions, HasChipLocation boot)
      Creates an empty machine.
      Parameters:
      machineDimensions - Size of the machine along the X and Y axes, in chips.
      boot - The coordinates of the chip used to boot the machine.

    • Machine

      public Machine(MachineDimensions machineDimensions, Iterable<Chip> chips, HasChipLocation boot)
      Creates a machine starting with the supplied chips.
      Parameters:
      machineDimensions - Size of the machine along the X and Y axes, in chips.
      chips - The chips in the machine.
      boot - The coordinates of the chip used to boot the machine.
      Throws:
      IllegalArgumentException - On an attempt to add a chip with a duplicate location of a chip already in the machine.

    • Machine

      public Machine(MachineBean bean)
      Creates a machine from a (serializable) descriptor.
      Parameters:
      bean - Descriptor holding the values to set.

  • Method Details

    • rebuild

      public Machine rebuild()
      Provides a machine without abnormal chips or links.

      This may be the original machine or it may be a shallow near-copy.

      Once this method is run it is expected that the original Machine is no longer used. The original internal objects are reused whenever possible. Changes made to the original Machine may or may not effect the new Machine. This includes changes made to the chips, their routers or their processors.

      For what makes up an abnormal link see findAbnormalLinks().

      For what makes up an abnormal chip see findAbnormalChips().

      Returns:
      A Machine (possibly the original one) without the abnormal bits.

    • rebuild

      public Machine rebuild(Set<ChipLocation> ignoreChips, Map<ChipLocation,EnumSet<Direction>> ignoreLinks)
      Provides a machine without ignored chips or links.

      This may be the original machine or it may be a shallow near copy.

      Once this method is run it is expected that the original Machine is no longer used. The original internal objects are reused whenever possible. Changes made to the original Machine may or may not effect the new Machine. This includes changes made to the chips, their routers or their processors.

      Parameters:
      ignoreChips - The locations of the chips (if any) that should not be in the rebuilt machine. Chips not specified to be ignored are not checked in any way. If this parameter is null the result of findAbnormalLinks() is used. If this parameter is empty it is ignored as are any location that do not represent a chip in the machine.
      ignoreLinks - A mapping of locations to directions of links that should not be in the rebuilt machine. Links not specified to be ignored are not checked in any way. If this parameter is null the result of findAbnormalChips() is used. If this parameter is empty it is ignored as are any location that do not represent a chip in the machine, or direction that do not represent an existing link.
      Returns:
      A Machine (possibly the original one) without the ignore/abnormal bits.

    • addChip

      public final void addChip(Chip chip)
      Add a chip to the machine.
      Parameters:
      chip - The chip to add to the machine.
      Throws:
      IllegalArgumentException - On an attempt to add a chip with a duplicate location of a chip already in the machine.

    • addChips

      public final void addChips(Iterable<Chip> chips)
      Add some chips to the machine.
      Parameters:
      chips - The chips to add.
      Throws:
      IllegalArgumentException - On an attempt to add a chip with a duplicate location of a chip already in the machine.

    • chips

      public final Collection<Chip> chips()
      Get the chips in the machine. The chips will be returned in the natural order of their ChipLocation.
      Returns:
      An unmodifiable ordered collection of the chips.

    • iterator

      public final Iterator<Chip> iterator()
      Get an iterator over the chips in this machine. The chips will be returned in the natural order of their ChipLocation.
      Specified by:
      iterator in interface Iterable<Chip>
      Returns:
      An iterator over the chips in this machine.

    • nChips

      public final int nChips()
      The number of chips on this machine.
      Returns:
      The number of chips on this machine.

    • chipCoordinates

      public final Set<ChipLocation> chipCoordinates()
      A set of all the locations of the chips in this machine. This set is guaranteed to iterate in the natural order of the locations.
      Returns:
      The (ordered) set of the locations of each chip in the machine.

    • chipsMap

      public final SortedMap<ChipLocation,Chip> chipsMap()
      An unmodifiable view over the map from locations to chips. This map is sorted by the natural order of the locations.
      Returns:
      An unmodifiable view over the map from locations to chips.

    • getChipAt

      public final Chip getChipAt(ChipLocation location)
      Get the chip at a specific (x, y) location. Will return null if hasChipAt for the same location returns false.
      Parameters:
      location - coordinates of the requested chip.
      Returns:
      A chip, or null if no chip found at that location.

    • getChipAt

      public final Chip getChipAt(HasChipLocation location)
      Get the chip at a specific (x, y) location. Will return null if hasChipAt for the same location returns false.
      Parameters:
      location - coordinates of the requested chip.
      Returns:
      A chip, or null if no chip found at that location.

    • getChipAt

      public final Chip getChipAt(int x, int y)
      Get the chip at a specific (x, y) location.

      Will return null if hasChipAt for the same location returns false.

      Parameters:
      x - The X-coordinate of the requested chip
      y - The Y-coordinate of the requested chip
      Returns:
      A chip, or null if no Chip found at that location.
      Throws:
      IllegalArgumentException - Thrown is either x or y is negative or too big (see MachineDefaults.validateChipLocation(int, int)).

    • hasChipAt

      public final boolean hasChipAt(ChipLocation location)
      Determine if a chip exists at the given coordinates.
      Parameters:
      location - coordinates of the requested chip.
      Returns:
      True if and only if the machine has a chip at that location.

    • hasChipAt

      public final boolean hasChipAt(HasChipLocation location)
      Determine if a chip exists at the given coordinates.
      Parameters:
      location - coordinates of the requested chip.
      Returns:
      True if and only if the machine has a chip at that location.

    • hasChipAt

      public final boolean hasChipAt(int x, int y)
      Determine if a chip exists at the given coordinates.
      Parameters:
      x - The X-coordinate of the requested chip
      y - The Y-coordinate of the requested chip
      Returns:
      True if and only if the machine has a Chip at that location.
      Throws:
      IllegalArgumentException - Thrown is either x or y is negative or too big (see MachineDefaults.validateChipLocation(int, int)).

    • hasLinkAt

      public final boolean hasLinkAt(ChipLocation source, Direction link)
      Determine if a link exists at the given coordinates.
      Parameters:
      source - The coordinates of the source of the link.
      link - The direction of the link.
      Returns:
      True if and only if the Machine/Chip has a link as specified.

    • getLocationOverLink

      public final ChipLocation getLocationOverLink(HasChipLocation source, Direction direction)
      Get the coordinates of a possible chip over the given link. This method will take wrap-arounds into account if appropriate.

      This method intentionally does not check if a chip at the resulting location already exists.

      Parameters:
      source - The coordinates of the source of the link.
      direction - The direction of the link to traverse
      Returns:
      Location of a possible chip that would be connected by this link.

    • getChipOverLink

      public final Chip getChipOverLink(HasChipLocation source, Direction direction)
      Get the existing chip over the given link. This method returns the destination chip without checking if the physical link is active.

      This method is just a combination of getLocationOverLink(HasChipLocation, Direction) and getChipAt(ChipLocation). It therefore takes wrap-around into account and does check for the existence of the destination chip.

      Parameters:
      source - The coordinates of the source of the link.
      direction - The direction of the link to traverse
      Returns:
      The destination chip connected by this (possible) link. or null if it does not exist.

    • maxChipX

      public final int maxChipX()
      The maximum possible X-coordinate of any chip in the board.

      Currently no check is carried out to guarantee there is actually a Chip with this X value.

      Returns:
      The maximum possible X-coordinate.

    • maxChipY

      public final int maxChipY()
      The maximum possible Y-coordinate of any chip in the board.

      Currently no check is carried out to guarantee there is actually a Chip with this Y value.

      Returns:
      The maximum possible Y-coordinate.

    • ethernetConnectedChips

      public List<Chip> ethernetConnectedChips()
      The chips in the machine that have control over an Ethernet connection. These are defined as the chip that have a non-null INET address. There is no guarantee regarding the order of the Chips.

      While these are typically the bottom-left chip of each board, this is not guaranteed.

      Returns:
      An unmodifiable list of the chips with an INET address.

    • spinnakerLinks

      public final Collection<SpinnakerLinkData> spinnakerLinks()
      Collection of the SpiNNaker links on this machine.
      Returns:
      An unmodifiable unordered collection of all the SpiNNaker links on this machine.

    • getSpinnakerLink

      public final SpinnakerLinkData getSpinnakerLink(int id, InetAddress address)
      Get a SpiNNaker link with a given ID.
      Parameters:
      id - The ID of the link
      address - The board address that this SpiNNaker link is associated with. If null the boot INET address will be used.
      Returns:
      The associated SpiNNaker link information, or null if not found.

    • getBootSpinnakerLink

      public final SpinnakerLinkData getBootSpinnakerLink(int id)
      Get a SpiNNaker link with a given ID on the boot chip.
      Parameters:
      id - The ID of the link
      Returns:
      The associated SpiNNaker link information, or null if not found.

    • addSpinnakerLinks

      public final void addSpinnakerLinks()
      Add SpiNNaker links that are on a given machine depending on the height and width and therefore version of the board.

      If a link already exists the original link is retain and that SpiNNaker link is not added.

    • normalizedLocation

      public final ChipLocation normalizedLocation(int x, int y)
      Converts x and y to a chip location, if required (and applicable) adjusting for wrap around.

      The only check that the coordinates are valid is to check they are greater than zero. Otherwise null is returned.

      Parameters:
      x - X coordinate
      y - Y coordinate
      Returns:
      A location based on x and y with possible wrap around, or null if either coordinate is less than zero or greater than the dimensions of the machine.

    • normalizedMove

      public final ChipLocation normalizedMove(HasChipLocation source, Direction direction)
      Returns the location you would get to from the source if you move in this direction, if required (and applicable) adjusting for wrap-around.

      No check is done to see if there is actually a chip at that location.

      Parameters:
      source - the original coordinates.
      direction - which way to move.
      Returns:
      A location based on a move in this direction with possible wrap around, or null if either coordinate is less than zero or greater than the dimensions of the machine.

    • normalizedLocation

      public final ChipLocation normalizedLocation(HasChipLocation location)
      Returns this location adjusted for wrap-arounds.

      No check is done to see if there is actually a chip at that location.

      Parameters:
      location - A location which may need to be corrected for wrap-arounds.
      Returns:
      A location based on a move in this direction with possible wrap around, or null if either coordinate is less than zero or greater than the dimensions of the machine.

    • getFpgaLink

      public final FPGALinkData getFpgaLink(FpgaId fpgaId, int fpgaLinkId, InetAddress address)
      Get an FPGA link data item that corresponds to the FPGA and FPGA link for a given board address.
      Parameters:
      fpgaId - The ID of the FPGA that the data is going through.
      fpgaLinkId - The link ID of the FPGA.
      address - The board address that this FPGA link is associated with.
      Returns:
      FPGA link data, or null if no such link has been added.

    • getFpgaLinks

      public final MappableIterable<FPGALinkData> getFpgaLinks()
      The added FPGA link data items. The iterable may be empty.

      No guarantee of order is provided.

      Returns:
      All added FPGA link data items.

    • getFpgaLinks

      public final MappableIterable<FPGALinkData> getFpgaLinks(InetAddress address)
      The added FPGA link data items for the given address. The iterable may be empty.

      No guarantee of order is provided.

      Parameters:
      address - The board address that this FPGA link is associated with.
      Returns:
      All added FPGA link data items for this address.

    • addFpgaLinks

      public final void addFpgaLinks()
      Add FPGA links that are on a given machine depending on the version of the board.

      Note: This implementation assumes the Ethernet-enabled chip is the 0, 0 chip on each board.

    • coresAndLinkOutputString

      public final String coresAndLinkOutputString()
      Get a string detailing the number of cores and links.

      Warning: the current implementation makes the simplification assumption that every link exists in both directions.

      Returns:
      A quick description of the machine.

    • bootChip

      public final Chip bootChip()
      The coordinates of the chip used to boot the machine. This is typically the Chip at (0, 0), and will typically have an associated InetAddress, but there is no guarantee of either of these facts.

      If no chip has been added to the machine at the boot, location this method returns null.

      Returns:
      The chip at the location specified as boot, or null.

    • iterChipsOnBoard

      public final MappableIterable<Chip> iterChipsOnBoard(Chip chip)
      The chips on the same board as the given chip.
      Parameters:
      chip - The exemplar chip from the board of interest
      Returns:
      Iterable of chips on the board. Not expected to be empty; the exemplar should be present.

    • maximumUserCoresOnChip

      public final int maximumUserCoresOnChip()
      The maximum number of user cores on any chip.

      A user core is defined as one that has not been reserved as a monitor.

      Returns:
      Maximum for at at least one core.

    • totalAvailableUserCores

      public final int totalAvailableUserCores()
      The total number of cores on the machine which are not monitor cores.
      Returns:
      The number of user cores over all chips.

    • totalCores

      public final int totalCores()
      The total number of cores on the machine including monitor cores.
      Returns:
      The number of cores over all Chips.

    • hasInverseLinkAt

      public boolean hasInverseLinkAt(ChipLocation chip, Direction direction)
      Check if the inverse link to the one described exists. This check is in two stages.
      1. Check that there is actually a second chip in the given direction from the input chip. There need not be an actual working link.
      2. Check that the second chip does have a working link back. (Inverse direction)
      Parameters:
      chip - Starting Chip which will be the Target of the actual link checked.
      direction - Original direction. This is the inverse of the direction in the link actually checked.
      Returns:
      True if and only if there is a active inverse link

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • findAbnormalLinks

      public Map<ChipLocation,EnumSet<Direction>> findAbnormalLinks()
      Returns a list of the abnormal links that are recommended for removal.

      The current implementation identifies the Links where there is no matching reverse link as abnormal. This includes case where the whole destination chip is missing.

      Future implementations may add other tests for abnormal Chips.

      Returns:
      A map of locations to sets of directions (hopefully empty) which identify links to remove

    • findAbnormalChips

      public Set<ChipLocation> findAbnormalChips()
      Returns a list of the abnormal chips that are recommended for removal.

      The current implementation identifies chips with no outgoing links as abnormal. Future implementations may add other tests for abnormal chips.

      Returns:
      A set (hopefully empty) of locations of chips to remove.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • difference

      public String difference(Machine other)
      Describes one difference found between this machine and another machine.

      This method will always return null if no difference is found between the two machines. So semantically is the same as equals except that this works if other is a superclass of machine in which case only the shared variables are compared.

      This method returns as soon as it has found a difference so there may be other not specified differences.

      Warning: This method could change over time, so there is no implied guarantee to the order that variables are checked or to the message that is returned. The only guarantee is that null is returned if no difference is detected.

      Parameters:
      other - Another machine to check if it has the same variables.
      Returns:
      null if no difference is detected, otherwise a string.

    • chipLocationDifference

      public String chipLocationDifference(Machine that)
      Describes the difference between chip location between two machines.

      This method is expected to only be called then there is a detected or expected difference between the two chip locations so will always return a message

      Warning: As this method is mainly a support method for difference(Machine), the returned result can be changed at any time.

      Parameters:
      that - Another machine with suspected difference in the location of chips.
      Returns:
      Some useful human readable information.

    • getBootEthernetAddress

      public InetAddress getBootEthernetAddress()
      Obtains the Boot Ethernet IP Address.
      Returns:
      The IPv4 Address of the boot chip (typically 0, 0)