Namespace AS2.Sim
Classes
AlgorithmException
Exception class for the case that an error occurred in the algorithm code of a particle. This covers all errors that cannot be recognized by the simulator because the error occurred directly in the algorithm code.
AmoebotSimException
Base class for exceptions thrown due to unintended behavior of the simulator.
Circuit
Represents a collection of partition sets that are connected into a single circuit.
Use the pooling mechanism (Get(int) and Free(Circuit)) to obtain and free instances.
A tree structure is used for merging circuits. When one circuit is merged into another, all of its children and the circuit itself are added as children to the other circuit. All children of a root circuit dispatch operations to their root.
CollisionChecker
Helper methods for detecting collisions in joint movements.
Collision checks work by tracking the movements of all edges in the system. Edges are created by all bonds and expanded, expanding and contracting particles in the system, as well as the boundaries of objects. If any two edges that do not coincide in one point at the start or the end of the movement intersect during the movement, a collision occurs.
EdgeMovement
Represents the movement of a length 1 edge during one round for the collision check.
If the edge belongs to an expanding or contracting particle, its start and end points will coincide either before or after the movement.
Use the pooling methods Create(Vector2Int, Vector2Int, Vector2Int, Vector2Int) and Release(EdgeMovement) to avoid allocating new memory for every new edge.
InitializationParticle
A stripped down particle class that is only used for system initialization. The data stored in this class is used to instantiate the proper particles and the associated algorithms when simulation mode is entered.
The attributes of these particles represent the parameters
of the associated algorithm's Init(...) method.
InvalidActionException
Exception class for the case that a particle tries to perform an invalid action like calling a method on a neighbor particle or in the wrong phase, or scheduling an impossible movement.
Message
Abstract base class for messages to be sent via the circuit system.
To use the messaging system, message types must be created as classes that inherit from this base class. Instances of the concrete message types can then be sent and received through partition sets, just like regular beeps.
Messages use a priority system to solve conflicts: If multiple particles send different messages on a circuit in the same round, only the message with the highest priority is received by the particles on the circuit. Thus, the GreaterThan(Message) and Equals(Message) methods must be implemented such that they define a strict total order on the set of all possible messages.
To ensure that messages can be saved and loaded correctly,
every subclass must provide a parameterless default
constructor and may only have simple members of
primitive types like int, bool,
string, or enums. In particular, no reference
types or data structures like lists or arrays are
supported as members.
OpenInitParticle
Specialization of the InitializationParticle class that provides direct access to some of its protected members. Should only be used by the system because setting these values directly can lead to inconsistent states.
Particle
The system-side representation of a particle.
This class stores all internal particle information that should be hidden from the developers of a particle algorithm. It also provides methods for changing the particle's state to be called by the ParticleSystem.
There is a 1:1 correspondence between Particle and ParticleAlgorithm instances. The conventional way to instantiate a pair of these objects is the following:
Particle part = new Particle(particleSystem, startPosition[, compassDir][, chirality][, initialHeadDir]);
part.isActive = true;
AlgorithmManager.Instance.Instantiate(algorithmId, part);
part.isActive = false;
p.InitWithAlgorithm();ParticleAction
Represents an action a particle can schedule when it is activated.
Some particle actions need to be scheduled because applying them immediately would violate the FSYNC execution model where all particles operate on the same snapshot of the system. Thus, these actions are scheduled and only applied after all particles have been activated.
ParticleAlgorithm
The abstract base class for particle algorithms in the Amoebot model.
Every algorithm that should run in the simulation must be implemented as a subclass of the ParticleAlgorithm class through its ActivateMove() and ActivateBeep() methods.
The subclass constructor must have the following signature and call the base class constructor:
public MyClass(Particle p) : base(p) { ... }The number of pins used by the algorithm must be specified by overriding the PinsPerEdge property.
Particle attributes that represent a part of the particle's state must be implemented using the ParticleAttribute<T> class.
public class MyParticle : ParticleAlgorithm {
ParticleAttribute<int> myIntAttr;
public MyParticle(Particle p) : base(p) {
myIntAttr = CreateAttributeInt("Fancy display name for myIntAttr", 42);
}
}ParticleAttributeBase
Abstract base class for all particle attributes.
Stores a reference to the Particle containing the attribute and the name of the attribute.
ParticleAttributeFactory
Factory class for creating and initializing ParticleAttribute<T> subclass instances.
ParticleAttributeWithHistory<T>
Abstract base class for particle attributes that adds functionality which should be hidden from the algorithm developer, especially the history methods.
ParticleAttribute_Bool
ParticleAttribute<T> subclass representing boolean values.
ParticleAttribute_Direction
ParticleAttribute<T> subclass representing direction values.
ParticleAttribute_Enum<T>
ParticleAttribute<T> subclass representing enum values.
To use this attribute, simply create an enum and use it
as the attribute's type parameter:
public enum State { IDLE, ROOT, LEADER }
public class MyParticleAlgo : ParticleAlgorithm {
public ParticleAttribute_Enum<State> myEnumAttr;
public MyParticleAlgo(Particle p) : base(p) {
myEnumAttr = new ParticleAttribute_Enum<State>(this, "Fancy display name", State.IDLE);
}
}ParticleAttribute_Float
ParticleAttribute<T> subclass representing float values.
ParticleAttribute_Int
ParticleAttribute<T> subclass representing integer values.
ParticleAttribute_PinConfiguration
ParticleAttribute<T> subclass representing pin configurations.
To write a value to a variable of this type, the SetValue(PinConfiguration) method must be used. It is not sufficient to apply changes to the PinConfiguration instance.
ParticleAttribute_String
ParticleAttribute<T> subclass representing strings.
ParticleAttribute<T>
Representation of an attribute that is part of a particle's state.
ParticleAlgorithm subclasses should use instances of ParticleAttribute<T> to represent their state variables. Only these attributes are displayed and editable in the simulation UI and recorded in a simulation history. They also provide correct read and write behavior in synchronous rounds, i.e., a ParticleAttribute<T> provides its most recently written value only to the particle it belongs to, and it always returns the value from the previous round to other particles.
ParticleAttribute<T>s are created using the factory
methods provided in the ParticleAlgorithm base class
(see CreateAttributeInt(string, int) etc.).
For example, an integer attribute is declared and initialized with the
value 3 as follows:
public class MyAlgorithm : ParticleAlgorithm {
public ParticleAttribute<int> myAttr;
public MyAlgorithm(Particle p) : base(p) {
myAttr = CreateAttributeInt("Fancy display name", 3);
}
}
Note the difference between the GetValue() and
GetCurrentValue() methods. Reading a ParticleAttribute<T>
like a variable of type T will return the same value as
GetValue(). Depending on the desired semantics, it may be helpful to
wrap attributes in properties when writing a particle algorithm.
ParticleException
Base class for exceptions thrown because a particle tried to perform an invalid operation or its algorithm code caused a problem.
Stores a reference to the particle that caused the exception.
ParticleFactory
Factory for instantiating Particles with specific ParticleAlgorithm implementations attached to them.
To be called by ParticleSystem to initialize the simulation.
ParticleObject
Represents objects in the particle system that the particles can interact with.
An object is a structure occupying a connected set of grid nodes. Particles can connect to objects through bonds and move the objects using the joint movement mechanisms. Objects also form bonds to each other. A particle can trigger a neighboring object to release all its bonds to other objects.
ParticleSystem
Main container for a system of particles in the grid together with the execution logic for simulating rounds.
Unlike other IReplayHistory implementations, the system will automatically reactivate the tracking state as soon as the marker is set to the latest round.
ParticleSystem_Utils
Utility methods and constants for computations done by the ParticleSystem.
PartitionSet
Developer API for partition sets.
This is part of the pin configuration API, see PinConfiguration.
A partition set is a set of connected pins within
a pin configuration. It belongs to an object
implementing the PinConfiguration
interface and may be changed through methods of
this API or through the pin configuration itself.
See also Pin.
Pin
Developer API for pins.
This is part of the pin configuration API, see PinConfiguration.
A pin represents a connection point on the edge of a particle through which it can communicate with neighboring particles using beeps or entire messages. Each edge incident to a particle has the same number of pins and the pins are ordered according to each particle's chirality. This means that the same pin may have different IDs for the two particles. Pins are locally identified by IDs computed from the label of the edge to which they belong and their offset on that edge.
Every pin is part of a pin configuration and as such, it belongs to a partition set at all times. Pins cannot be created or destroyed, they can only be moved from one partition set to another.
PinConfiguration
Developer API for pin configuration definition.
Represents a complete pin configuration for a fixed expansion state. The object contains PartitionSet and Pin instances which are connected such that changes to one of the objects may cause changes in any of the other objects. For example, adding a pin to a partition set causes it to be removed from the partition set it was previously contained in.
The position of a pin is uniquely defined by the edge it is located on and its offset on the edge. The pin indices on each edge are 0-based and increase in (local) counter-clockwise direction.
Pins and partition sets have fixed IDs from 0
to NumPins - 1. The pin IDs are
defined as edgeLabel * PinsPerEdge + edgeOffset.
This means that the pins are numbered consecutively in
(local) counter-clockwise direction, starting at edge label 0
and edge offset 0.
SimulationException
Exception class for the case that an error occurred during the simulation that cannot be directly attributed to a single particle.
SimulatorException
Base class for exceptions thrown by the simulator due to a problem during the simulation or invalid data or usage.
SimulatorStateException
Exception class for the case that some operation of the simulator outside of the Amoebot simulation failed. This includes operations started in the wrong simulator state, save and load issues, and invalid input data.
SysPartitionSet
System-side implementation of the abstract base class PartitionSet, which declares the API for the developer.
SysPin
System-side implementation of the abstract base class Pin, which declares the API for the developer.
SysPinConfiguration
System-side implementation of the abstract base class PinConfiguration, which declares the API for the developer.
Can generate a compressed representation to enable saving and loading pin configurations, see PinConfigurationSaveData.
ValueHistoryBondInfo
Implementation of ValueHistory<T> storing BondMovementInfoList structs.
ValueHistoryJointMovement
Implementation of ValueHistory<T> storing JointMovementInfo structs.
ValueHistoryMessage
Specialized value history that stores Message data and compares messages using their custom equality check.
ValueHistoryPinConfiguration
Specialized value history that stores compressed pin configuration data.
Each pin configuration is only stored once to save memory. The history itself simply stores identifiers instead of whole pin configurations.
ValueHistory<T>
Represents a variable of type T and its
entire value history starting at some round.
The history can be extended by adding records for later rounds or updating the value for the currently last round, but it cannot be changed for any round before the last round with a record unless it is cut off.
The value in a round before the first recorded round is not defined.
The history also provides a marker mechanism that allows the value history to be traversed in sequence. The marker starts at the initial round and tracks the latest round until it is set to some round using SetMarkerToRound(int) or moved by one step using StepBack() or StepForward(). It can be reset to track the last round using ContinueTracking().
Structs
BondMovementInfo
Serializable representation of a single bond movement. Describes the two locations of a bond before and after a movement round. Also contains some graphical info.
BondMovementInfoList
Serializable representation of a list of bond movements.
CollisionChecker.DebugLine
Simple container for data required to draw lines that show a collision in the system.
JointMovementInfo
Serializable representation of the joint movement info describing a single particle's movement.
Neighbor<T>
A simple container for neighbor search results.
Contains a reference to a neighbor particle, the local direction in which it was found, and a flag indicating whether the direction is relative to the querying particle's head or tail.
Interfaces
IParticleAttribute
Interface defining how particle attributes can be used by the System and the UI.
IParticleObject
Represents an object in the particle system that can be detected and moved around by the particles.
IReplayHistory
Interface defining methods for objects that store a history and that can be reset to a previous point in time.
Time is simply measured in rounds. The round number equals the number of simulation rounds executed until that point in time.
By default, the object's state evolves with the rounds that are simulated. If the tracking marker is reset to a particular round, the object reverts to its previous state recorded for that round. In this state, the object cannot be part of the simulation anymore, but the marker can be used to step through the recorded rounds or jump to any valid round. As soon as the state tracking is reactivated, the marker will follow the latest recorded state and the object will evolve with the simulation again.
Enums
ActionType
All possible movement actions of a particle.