Class 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.

Example for attribute initialization in subclass:

public class MyParticle : ParticleAlgorithm {
    ParticleAttribute<int> myIntAttr;
    public MyParticle(Particle p) : base(p) {
        myIntAttr = CreateAttributeInt("Fancy display name for myIntAttr", 42);
    }
}

Note that the display names of particle attributes must be unique because they are used to identify attributes when loading a saved simulation state.

Inheritance

object

ParticleAlgorithm

BeepFailureTestParticle

BinOpTestParticle

BoundaryTestParticle

BoundaryTestSubParticle

ChiralityAndCompassParticle

CollisionTestAlgoParticle

CollisionTestAlgo2Particle

ExpandedCircuitTestParticle

JMTestParticle

LeaderElectionParticle

LineFormationParticleSync

ObjectTestParticle

PASCTestAlgoParticle

SmartMaterialParticle

SubroutineTestParticle

SubroutineTest2Particle

Namespace: AS2.Sim

Assembly: .dll

Syntax

public abstract class ParticleAlgorithm

Constructors

ParticleAlgorithm(Particle)

Declaration

public ParticleAlgorithm(Particle particle)

Parameters

Type	Name	Description
Particle	particle

Fields

particle

Reference to the particle's system representation.

Declaration

private Particle particle

Field Value

Type	Description
Particle

Properties

GenerationMethod

The full type name of the algorithm's generation method. This method must be a subclass of AlgorithmGenerator.

Declaration

public static string GenerationMethod { get; }

Property Value

Type	Description
string

Name

The display name of the algorithm. Must be unique among all algorithms.

Declaration

public static string Name { get; }

Property Value

Type	Description
string

PinsPerEdge

The number of pins on each edge.

This number must be the same constant for all particles.

Declaration

public abstract int PinsPerEdge { get; }

Property Value

Type	Description
int

Methods

ActivateBeep()

This is the second part of the main activation logic of the particle. It is called exactly once in each round, after the movements scheduled in ActivateMove() have been executed, and should contain the algorithm code that implements the look-compute-beep cycle.

Inside of this method, particles are allowed to change their pin configuration and send beeps and messages on the updated configuration.

Note that beeps and messages sent in the current round will be readable in both the ActivateMove() and ActivateBeep() calls in the next round.

Declaration

public abstract void ActivateBeep()

ActivateMove()

This is one part of the main activation logic of the particle. It is called exactly once in each round and should contain the algorithm code that implements the look-compute-move cycle. After the movements are executed, ActivateBeep() is called within the same round.

Inside of this method, particles are allowed to release bonds, define which bonds should be marked, and schedule movements. Only the last movement operation scheduled in this method will be applied.

Declaration

public abstract void ActivateMove()

BondActive(Direction, bool)

Checks if the specified bond is still active or marked to be released. Always returns true when called in ActivateBeep().

Declaration

public bool BondActive(Direction locDir, bool head = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction into which the bond is pointing.
bool	head	If the particle is expanded, this flag indicates whether the bond is located at the head or the tail.

Returns

Type	Description
bool	true if and only if the specified bond is still marked as active.

BondMarked(Direction, bool)

Checks if the bond at the given label is marked for special behavior. Always returns false when called in ActivateBeep().

See MarkBond(Direction, bool).

Declaration

public bool BondMarked(Direction locDir, bool head = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction into which the bond is pointing.
bool	head	If the particle is expanded, this flag indicates whether the bond is located at the head or the tail.

Returns

Type	Description
bool	true if and only if the bond at the given position has been marked.

CheckActive(string)

Checks if the particle is currently active and throws an exception if it is not.

Used to guard operations from being called on particles that are not currently active.

Declaration

private void CheckActive(string errorMessage)

Parameters

Type	Name	Description
string	errorMessage	The error message to be used for the exception.

Exceptions

Type	Condition
InvalidActionException	Thrown if this particle is currently not active.

CheckBeep(string, bool)

Checks if we are currently in the beep phase and logs a warning message if we are not.

Declaration

private bool CheckBeep(string warningMessage, bool exception = false)

Parameters

Type	Name	Description
string	warningMessage	The warning message to be logged if we are not in the beep phase. No warning will be logged if this is null.
bool	exception	If true, throw an exception with the given message.

Returns

Type	Description
bool	true if and only if the system is currently simulating the beep phase.

CheckMove(string, bool)

Checks if we are currently in the move phase and logs a warning message if we are not.

Declaration

private bool CheckMove(string warningMessage, bool exception = false)

Parameters

Type	Name	Description
string	warningMessage	The warning message to be logged if we are not in the move phase. No warning will be logged if this is null.
bool	exception	If true, throw an exception with the given message.

Returns

Type	Description
bool	true if and only if the system is currently simulating the move phase.

Contract(bool)

Contracts this particle into the grid node that is currently occupied by the particle's head or tail, depending on head. After the contraction, the head and tail will both occupy this node. Only works in ActivateMove().

Note that movements are only applied at the end of a round, i.e., after the activation is over. This means that calling this method will have no immediate effect.

See also ContractHead(), ContractTail().

Declaration

public void Contract(bool head)

Parameters

Type	Name	Description
bool	head	If true, contract into the particle's head, otherwise contract into the tail.

ContractHead()

Contracts this particle into the grid node that is currently occupied by the particle's head. After the contraction, the head and tail will both occupy this node. Only works in ActivateMove().

Note that movements are only applied at the end of a round, i.e., after the activation is over. This means that calling this method will have no immediate effect.

See also Expand(Direction), ContractTail(), Contract(bool), PullHandoverHead(Direction).

Declaration

public void ContractHead()

ContractTail()

Contracts this particle into the grid node that is currently occupied by the particle's tail. After the contraction, the head and tail will both occupy this node. Only works in ActivateMove().

Note that movements are only applied at the end of a round, i.e., after the activation is over. This means that calling this method will have no immediate effect.

See also Expand(Direction), ContractHead(), Contract(bool), PullHandoverTail(Direction).

Declaration

public void ContractTail()

CreateAttributeBool(string, bool)

Creates a new ParticleAttribute<T> representing a boolean value.

Declaration

public ParticleAttribute<bool> CreateAttributeBool(string name, bool initialValue = false)

Parameters

Type	Name	Description
string	name	The name of the attribute to be displayed in the UI. Must be unique for saving and loading of simulation states to work correctly.
bool	initialValue	The initial attribute value.

Returns

Type	Description
ParticleAttribute<bool>	The ParticleAttribute<T> initialized to initialValue.

CreateAttributeDirection(string, Direction)

Creates a new ParticleAttribute<T> representing a direction.

The Direction enum specifies which values can be stored in the attribute.

Declaration

public ParticleAttribute<Direction> CreateAttributeDirection(string name, Direction initialValue = Direction.NONE)

Parameters

Type	Name	Description
string	name	The name of the attribute to be displayed in the UI. Must be unique for saving and loading of simulation states to work correctly.
Direction	initialValue	The initial attribute value.

Returns

Type	Description
ParticleAttribute<Direction>	The ParticleAttribute<T> initialized to initialValue.

CreateAttributeEnum<EnumT>(string, EnumT)

Creates a new ParticleAttribute<T> representing an enum value.

Declaration

public ParticleAttribute<EnumT> CreateAttributeEnum<EnumT>(string name, EnumT initialValue) where EnumT : Enum

Parameters

Type	Name	Description
string	name	The name of the attribute to be displayed in the UI. Must be unique for saving and loading of simulation states to work correctly.
EnumT	initialValue	The initial attribute value.

Returns

Type	Description
ParticleAttribute<EnumT>	The ParticleAttribute<T> initialized to initialValue.

Type Parameters

Name	Description
EnumT	The enum specifying the possible values of this attribute.

CreateAttributeFloat(string, float)

Creates a new ParticleAttribute<T> representing a float value.

Declaration

public ParticleAttribute<float> CreateAttributeFloat(string name, float initialValue = 0)

Parameters

Type	Name	Description
string	name	The name of the attribute to be displayed in the UI. Must be unique for saving and loading of simulation states to work correctly.
float	initialValue	The initial attribute value.

Returns

Type	Description
ParticleAttribute<float>	The ParticleAttribute<T> initialized to initialValue.

CreateAttributeInt(string, int)

Creates a new ParticleAttribute<T> representing an integer value.

Declaration

public ParticleAttribute<int> CreateAttributeInt(string name, int initialValue = 0)

Parameters

Type	Name	Description
string	name	The name of the attribute to be displayed in the UI. Must be unique for saving and loading of simulation states to work correctly.
int	initialValue	The initial attribute value.

Returns

Type	Description
ParticleAttribute<int>	The ParticleAttribute<T> initialized to initialValue.

CreateAttributePinConfiguration(string, PinConfiguration)

Creates a new ParticleAttribute<T> representing a pin configuration.

Note that PinConfiguration is a reference type but particle attributes have value semantics. This means that changes to the value of an attribute of this type must be "committed" by calling the SetValue(T) method. It is not sufficient to call methods on the pin configuration instance.

Additionally, PinConfigurations stored in attributes do not retain any of their status flags, i.e., saving the current pin configuration in an attribute and then reading it will return a pin configuration that is identical to the current one but that is not marked as the current configuration and can thus not be used to read received beeps and messages. The same holds for storing the planned pin configuration.

Note that reading stored pin configurations of other particles is not supported.

Declaration

public ParticleAttribute<PinConfiguration> CreateAttributePinConfiguration(string name, PinConfiguration initialValue)

Parameters

Type	Name	Description
string	name	The name of the attribute to be displayed in the UI. Must be unique for saving and loading of simulation states to work correctly.
PinConfiguration	initialValue	The initial attribute value.

Returns

Type	Description
ParticleAttribute<PinConfiguration>	The ParticleAttribute<T> initialized to initialValue.

CreateAttributeString(string, string)

Creates a new ParticleAttribute<T> representing a string value.

Declaration

public ParticleAttribute<string> CreateAttributeString(string name, string initialValue = "")

Parameters

Type	Name	Description
string	name	The name of the attribute to be displayed in the UI. Must be unique for saving and loading of simulation states to work correctly.
string	initialValue	The initial attribute value.

Returns

Type	Description
ParticleAttribute<string>	The ParticleAttribute<T> initialized to initialValue.

Expand(Direction)

Expands this particle in the specified local direction. After the expansion, the particle's head will occupy the grid node in that direction, and its tail will remain at its current position. Only works in ActivateMove().

Note that movements are only applied at the end of a round, i.e., after the activation is over. This means that calling this method will have no immediate effect.

See also ContractHead(), ContractTail(), PushHandover(Direction).

Declaration

public void Expand(Direction locDir)

Parameters

Type	Name	Description
Direction	locDir	The local direction in which to expand.

FindFirstNeighborObjectWithProperty(Func<IParticleObject, bool>, out Neighbor<IParticleObject>, Direction, bool, bool, int)

Searches for the first neighboring object in the specified range that satisfies the given property.

Declaration

public bool FindFirstNeighborObjectWithProperty(Func<IParticleObject, bool> prop, out Neighbor<IParticleObject> neighbor, Direction startDir = Direction.E, bool startAtHead = true, bool withChirality = true, int maxNumber = -1)

Parameters

Type	Name	Description
Func<IParticleObject, bool>	prop	The property the neighbor object has to satisfy.
Neighbor<IParticleObject>	neighbor	The first neighbor object that is encountered, or Null if no neighbor is found.
Direction	startDir	The local direction of the first port to search at.
bool	startAtHead	Indicates whether startDir is relative to the particle's head. Has no effect for contracted particles.
bool	withChirality	If true, the search progresses in the particle's local counter-clockwise direction, otherwise in the local clockwise direction.
int	maxNumber	The maximum number of ports to check. The maximum value is 6 for contracted particles and 10 for expanded particles. Negative values automatically select the maximum number.

Returns

Type	Description
bool	true if and only if a neighbor object was found.

FindFirstNeighborWithProperty<T>(Func<T, bool>, out Neighbor<T>, Direction, bool, bool, int)

Searches for the first neighboring particle in the specified range that satisfies the given property.

Declaration

public bool FindFirstNeighborWithProperty<T>(Func<T, bool> prop, out Neighbor<T> neighbor, Direction startDir = Direction.E, bool startAtHead = true, bool withChirality = true, int maxNumber = -1) where T : ParticleAlgorithm

Parameters

Type	Name	Description
Func<T, bool>	prop	The property the neighbor has to satisfy.
Neighbor<T>	neighbor	The first neighbor particle that is encountered, or Null if no neighbor is found.
Direction	startDir	The local direction of the first port to search at.
bool	startAtHead	Indicates whether startDir is relative to the particle's head. Has no effect for contracted particles.
bool	withChirality	If true, the search progresses in the particle's local counter-clockwise direction, otherwise in the local clockwise direction.
int	maxNumber	The maximum number of ports to check. The maximum value is 6 for contracted particles and 10 for expanded particles. Negative values automatically select the maximum number.

Returns

Type	Description
bool	true if and only if a neighbor was found.

Type Parameters

Name	Description
T	The algorithm type to search for. Should be the same type as the algorithm that calls this method.

FindFirstNeighbor<T>(out Neighbor<T>, Direction, bool, bool, int)

Searches for the first neighboring particle in the specified range.

Declaration

public bool FindFirstNeighbor<T>(out Neighbor<T> neighbor, Direction startDir = Direction.E, bool startAtHead = true, bool withChirality = true, int maxNumber = -1) where T : ParticleAlgorithm

Parameters

Type	Name	Description
Neighbor<T>	neighbor	The first neighbor particle that is encountered, or Null if no neighbor is found.
Direction	startDir	The local direction of the first port to search.
bool	startAtHead	Indicates whether startDir is relative to the particle's head. Has no effect for contracted particles.
bool	withChirality	If true, the search progresses in the particle's local counter-clockwise direction, otherwise in the local clockwise direction.
int	maxNumber	The maximum number of ports to check. The maximum value is 6 for contracted particles and 10 for expanded particles. Negative values automatically select the maximum number.

Returns

Type	Description
bool	true if and only if a neighbor was found.

Type Parameters

Name	Description
T	The algorithm type to search for. Should be the same type as the algorithm that calls this method.

FindFirstObjectNeighbor(out Neighbor<IParticleObject>, Direction, bool, bool, int)

Searches for the first neighboring object in the specified range.

Declaration

public bool FindFirstObjectNeighbor(out Neighbor<IParticleObject> neighbor, Direction startDir = Direction.E, bool startAtHead = true, bool withChirality = true, int maxNumber = -1)

Parameters

Type	Name	Description
Neighbor<IParticleObject>	neighbor	The first neighbor object that is encountered, or Null if no neighbor is found.
Direction	startDir	The local direction of the first port to search.
bool	startAtHead	Indicates whether startDir is relative to the particle's head. Has no effect for contracted particles.
bool	withChirality	If true, the search progresses in the particle's local counter-clockwise direction, otherwise in the local clockwise direction.
int	maxNumber	The maximum number of ports to check. The maximum value is 6 for contracted particles and 10 for expanded particles. Negative values automatically select the maximum number.

Returns

Type	Description
bool	true if and only if a neighbor object was found.

FindNeighborObjects(Direction, bool, bool, int, int)

Searches for neighboring objects in the specified range.

Declaration

public List<Neighbor<IParticleObject>> FindNeighborObjects(Direction startDir = Direction.E, bool startAtHead = true, bool withChirality = true, int maxSearch = -1, int maxReturn = -1)

Parameters

Type	Name	Description
Direction	startDir	The local direction of the first port to search.
bool	startAtHead	Indicates whether startDir is relative to the particle's head. Has no effect for contracted particles.
bool	withChirality	If true, the search progresses in the particle's local counter-clockwise direction, otherwise in the local clockwise direction.
int	maxSearch	The maximum number of ports to search. Will always be limited to the total number of ports. Negative values mean that all ports will be searched.
int	maxReturn	The maximum number of neighbors to return. The same restrictions as for maxSearch apply.

Returns

Type	Description
List<Neighbor<IParticleObject>>	A list containing all discovered neighbor objects.

FindNeighborObjectsWithProperty(Func<IParticleObject, bool>, Direction, bool, bool, int, int)

Searches for neighboring objects in the specified range that satisfy the given property.

Declaration

public List<Neighbor<IParticleObject>> FindNeighborObjectsWithProperty(Func<IParticleObject, bool> prop, Direction startDir = Direction.E, bool startAtHead = true, bool withChirality = true, int maxSearch = -1, int maxReturn = -1)

Parameters

Type	Name	Description
Func<IParticleObject, bool>	prop	The property the neighbor objects have to satisfy.
Direction	startDir	The local direction of the first port to search.
bool	startAtHead	Indicates whether startDir is relative to the particle's head. Has no effect for contracted particles.
bool	withChirality	If true, the search progresses in the particle's local counter-clockwise direction, otherwise in the local clockwise direction.
int	maxSearch	The maximum number of ports to search. Will always be limited to the total number of ports. Negative values mean that all ports will be searched.
int	maxReturn	The maximum number of neighbors to return. The same restrictions as for maxSearch apply.

Returns

Type	Description
List<Neighbor<IParticleObject>>	A list containing all discovered neighbor objects.

FindNeighborsWithProperty<T>(Func<T, bool>, Direction, bool, bool, int, int)

Searches for neighboring particles in the specified range that satisfy the given property.

Declaration

public List<Neighbor<T>> FindNeighborsWithProperty<T>(Func<T, bool> prop, Direction startDir = Direction.E, bool startAtHead = true, bool withChirality = true, int maxSearch = -1, int maxReturn = -1) where T : ParticleAlgorithm

Parameters

Type	Name	Description
Func<T, bool>	prop	The property the neighbors have to satisfy.
Direction	startDir	The local direction of the first port to search.
bool	startAtHead	Indicates whether startDir is relative to the particle's head. Has no effect for contracted particles.
bool	withChirality	If true, the search progresses in the particle's local counter-clockwise direction, otherwise in the local clockwise direction.
int	maxSearch	The maximum number of ports to search. Will always be limited to the total number of ports. Negative values mean that all ports will be searched.
int	maxReturn	The maximum number of neighbors to return. The same restrictions as for maxSearch apply.

Returns

Type	Description
List<Neighbor<T>>	A list containing all discovered neighbors.

Type Parameters

Name	Description
T	The algorithm type to search for. Should be the same type as the algorithm that calls this method.

FindNeighbors<T>(Direction, bool, bool, int, int)

Searches for neighboring particles in the specified range.

Declaration

public List<Neighbor<T>> FindNeighbors<T>(Direction startDir = Direction.E, bool startAtHead = true, bool withChirality = true, int maxSearch = -1, int maxReturn = -1) where T : ParticleAlgorithm

Parameters

Type	Name	Description
Direction	startDir	The local direction of the first port to search.
bool	startAtHead	Indicates whether startDir is relative to the particle's head. Has no effect for contracted particles.
bool	withChirality	If true, the search progresses in the particle's local counter-clockwise direction, otherwise in the local clockwise direction.
int	maxSearch	The maximum number of ports to search. Will always be limited to the total number of ports. Negative values mean that all ports will be searched.
int	maxReturn	The maximum number of neighbors to return. The same restrictions as for maxSearch apply.

Returns

Type	Description
List<Neighbor<T>>	A list containing all discovered neighbors.

Type Parameters

Name	Description
T	The algorithm type to search for. Should be the same type as the algorithm that calls this method.

GetAlgorithmName()

Finds the official name of this algorithm. This is the name used by the algorithm manager to identify the algorithms. It is defined by the static Name property.

Declaration

public string GetAlgorithmName()

Returns

Type	Description
string	The official name of this algorithm, if it is defined, otherwise the full name of the class.

GetContractedPinConfiguration()

Creates a pin configuration for the contracted state with the default singleton pattern.

The returned object can be used to define the next pin configuration if the particle plans to perform a contraction movement in this round.

GetNextPinConfiguration(), GetExpandedPinConfiguration(Direction), SetNextPinConfiguration(PinConfiguration).

Declaration

public PinConfiguration GetContractedPinConfiguration()

Returns

Type	Description
PinConfiguration	A new singleton pin configuration for the contracted state that can be modified arbitrarily.

GetCurrPinConfiguration()

Returns a copy of the pin configuration from the beginning of the round.

This object can be used for reading beeps and messages that were received. It can also be modified and set as the next pin configuration. After the first modification, it cannot be used for reading beeps and messages anymore.

See also GetContractedPinConfiguration(), GetExpandedPinConfiguration(Direction), SetNextPinConfiguration(PinConfiguration), GetNextPinConfiguration().

Declaration

public PinConfiguration GetCurrPinConfiguration()

Returns

Type	Description
PinConfiguration	A copy of the pin configuration from the beginning of the current round.

GetCurrentPCAsPlanned()

Same as GetPlannedPinConfiguration() but also sets the current pin configuration to be the planned one such that it can immediately be used to send beeps and messages.

Declaration

[Obsolete("This method is part of the old pin configuration system and does not work anymore. To read received beeps and messages, call the methods directly in the algorithm code or use GetCurrPinConfiguration. To get a pin configuration that can be modified for the next round, use GetNextPinConfiguration.")]
public PinConfiguration GetCurrentPCAsPlanned()

Returns

Type	Description
PinConfiguration	The current pin configuration, already planned for the next round.

GetCurrentPinConfiguration()

Returns a copy of the pin configuration at the beginning of the round.

This object can be used as a basis for defining the new pin configuration after the round if the particle does not perform a movement. It also provides the interface for reading beeps and messages that were received.

See also GetContractedPinConfiguration(), GetExpandedPinConfiguration(Direction), SetNextPinConfiguration(PinConfiguration), GetPlannedPinConfiguration().

Declaration

[Obsolete("This method is part of the old pin configuration system and does not work anymore. To read received beeps and messages, call the methods directly in the algorithm code or use GetCurrPinConfiguration. To get a pin configuration that can be modified for the next round, use GetNextPinConfiguration.")]
public PinConfiguration GetCurrentPinConfiguration()

Returns

Type	Description
PinConfiguration	A copy of the pin configuration at the beginning of the current round.

GetExpandedPinConfiguration(Direction)

Creates a pin configuration for an expanded state with the default singleton pattern.

The returned object can be used to define the next pin configuration if the particle plans to perform an expansion movement such that its head direction after the movement is headDirection.

See also GetNextPinConfiguration(), GetContractedPinConfiguration(), SetNextPinConfiguration(PinConfiguration).

Declaration

public PinConfiguration GetExpandedPinConfiguration(Direction headDirection)

Parameters

Type	Name	Description
Direction	headDirection	The head direction defining the expansion state for which the pin configuration should be created.

Returns

Type	Description
PinConfiguration	A new singleton pin configuration for the specified expansion state that can be modified arbitrarily.

GetMainColor()

Returns the main color of this particle.

Call IsMainColorSet() first to check if the color has been set or not. If not, the return value of this method has no meaning.

Declaration

public Color GetMainColor()

Returns

Type	Description
Color	The currently set main color of the particle, if it has been set previously.

GetNeighborAt(Direction, bool)

Gets this particle's neighbor in the given local direction. The position to check is determined in the same way as in HasNeighborAt(Direction, bool).

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation.

Declaration

public ParticleAlgorithm GetNeighborAt(Direction locDir, bool fromHead = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction from which to get the neighbor particle.
bool	fromHead	If true, look from the particle's head, otherwise look from the particle's tail (only relevant if this particle is expanded).

Returns

Type	Description
ParticleAlgorithm	The neighboring particle in the specified position.

GetNextPinConfiguration()

Returns the pin configuration to be set at the end of the round.

This object can be modified and used to schedule beeps and messages. By default, this is a copy of the current pin configuration if no movement was performed and a singleton configuration otherwise.

See also GetContractedPinConfiguration(), GetExpandedPinConfiguration(Direction), SetNextPinConfiguration(PinConfiguration), GetCurrPinConfiguration().

Declaration

public PinConfiguration GetNextPinConfiguration()

Returns

Type	Description
PinConfiguration	The pin configuration to be set at the end of the current round.

GetObjectAt(Direction, bool)

Gets this particle's neighbor object in the given local direction. The position to check is determined in the same way as in HasObjectAt(Direction, bool).

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation.

Declaration

public IParticleObject GetObjectAt(Direction locDir, bool fromHead = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction from which to get the neighbor object.
bool	fromHead	If true, look from the particle's head, otherwise look from the particle's tail (only relevant if this particle is expanded).

Returns

Type	Description
IParticleObject	The neighboring object in the specified position.

GetPlannedPinConfiguration()

Returns the pin configuration set using SetNextPinConfiguration(PinConfiguration) in this round. Always returns null when called in ActivateMove().

Declaration

[Obsolete("This method is part of the old pin configuration system and does not work anymore. To send beeps and messages, call the methods directly in the algorithm code or use GetNextPinConfiguration.")]
public PinConfiguration GetPlannedPinConfiguration()

Returns

Type	Description
PinConfiguration	The pin configuration planned to be applied at the end of the current round. null if no configuration was planned yet.

GetReceivedMessageOfPartitionSet(int)

Returns the message received by the specified partition set, if it has received a message.

Declaration

public Message GetReceivedMessageOfPartitionSet(int partitionSetID)

Parameters

Type	Name	Description
int	partitionSetID	The ID of the partition set to get the message from.

Returns

Type	Description
Message	A Message instance received by the partition set with ID partitionSetID, if it has received one, otherwise null.

GetReceivedMessageOfPin(Direction, int, bool)

Returns the message received by the specified pin, if it has received a message.

Declaration

public Message GetReceivedMessageOfPin(Direction direction, int offset, bool head = true)

Parameters

Type	Name	Description
Direction	direction	The direction of the edge containing the pin.
int	offset	The pin offset on the specified edge. Must be in the range 0,...,PinsPerEdge-1.
bool	head	If the particle is expanded, use this flag to indicate whether the edge belongs to the particle's head or not.

Returns

Type	Description
Message	A Message instance received by the partition set with ID partitionSetID, if it has received one, otherwise null.

HasNeighborAt(Direction, bool)

Checks if this particle has a neighboring particle in the given local direction. For expanded particles, there are two different nodes in the same local direction, one seen from the particle's head and one seen from its tail.

See also GetNeighborAt(Direction, bool).

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation.

Declaration

public bool HasNeighborAt(Direction locDir, bool fromHead = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction in which to search for a neighbor particle.
bool	fromHead	If true, look from the particle's head, otherwise look from the particle's tail (only relevant if this particle is expanded).

Returns

Type	Description
bool	true if and only if there is a different particle in the specified position.

HasObjectAt(Direction, bool)

Checks if this particle has a neighboring object in the given local direction. For expanded particles, there are two different nodes in the same local direction, one seen from the particle's head and one seen from its tail.

See also HasNeighborAt(Direction, bool).

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation.

Declaration

public bool HasObjectAt(Direction locDir, bool fromHead = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction in which to search for a neighboring object.
bool	fromHead	If true, look from the particle's head, otherwise look from the particle's tail (only relevant if this particle is expanded).

Returns

Type	Description
bool	true if and only if there is a grid node occupied by an object in the specified position.

HeadDirection()

Returns the local direction pointing from the particle's tail towards its head.

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation. Use HeadDirection_After() to get the predicted value for after the round.

Declaration

public Direction HeadDirection()

Returns

Type	Description
Direction	The local direction pointing from the particle's tail towards its head, if it is expanded, otherwise -1.

HeadDirection_After()

Like HeadDirection(), but returns the predicted value for after the round.

Declaration

public Direction HeadDirection_After()

Returns

Type	Description
Direction	The local direction pointing from the particle's tail towards its head, if it is expanded, otherwise -1.

HideBond(Direction, bool)

Hides the bond at the given label without releasing it.

See ShowBond(Direction, bool), IsBondVisible(Direction, bool).

Declaration

public void HideBond(Direction locDir, bool head = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction into which the bond is pointing.
bool	head	If the particle is expanded, this flag indicates whether the bond is located at the head or the tail

IsBondVisible(Direction, bool)

Checks if the bond at the given label is visible. Always returns false when called in ActivateBeep().

See HideBond(Direction, bool), ShowBond(Direction, bool).

Declaration

public bool IsBondVisible(Direction locDir, bool head = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction into which the bond is pointing.
bool	head	If the particle is expanded, this flag indicates whether the bond is located at the head or the tail

Returns

Type	Description
bool	true if and only if the bond at the given position is currently visible.

IsContracted()

Checks if the particle is currently contracted, i.e., occupies exactly one node of the grid.

See IsExpanded().

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation. Use IsContracted_After() to get the predicted value for after the round.

Declaration

public bool IsContracted()

Returns

Type	Description
bool	true if and only if the particle is contracted.

IsContracted_After()

Like IsContracted(), but returns the predicted value for after the round

Declaration

public bool IsContracted_After()

Returns

Type	Description
bool	true if and only if the particle will be contracted at the end of the round if its planned movements succeed.

IsExpanded()

Checks if the particle is currently expanded, i.e., occupies 2 neighboring grid nodes simultaneously.

See IsContracted().

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation. Use IsExpanded_After() to get the predicted value for after the round.

Declaration

public bool IsExpanded()

Returns

Type	Description
bool	true if and only if the particle is expanded.

IsExpanded_After()

Like IsExpanded(), but returns the predicted value for after the round

Declaration

public bool IsExpanded_After()

Returns

Type	Description
bool	true if and only if the particle will be expanded at the end of the round if its planned movements succeed.

IsFinished()

Checks whether this particle has finished its algorithm.

Override this method to return true when a particle is done executing the algorithm. Once all particles in the system are finished, the simulation will stop automatically. When a particle's state results in this method returning true, its activation methods should not change its state any more.

Declaration

public virtual bool IsFinished()

Returns

Type	Description
bool	true if and only if this particle has finished its algorithm.

IsHeadAt(Direction, bool)

Checks if the part of the neighboring particle in the given local direction is the neighbor's head. The position to check is determined in the same way as in HasNeighborAt(Direction, bool).

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation.

Declaration

public bool IsHeadAt(Direction locDir, bool fromHead = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction from which to get the neighbor particle.
bool	fromHead	If true, look from the particle's head, otherwise look from the particle's tail (only relevant if this particle is expanded.)

Returns

Type	Description
bool	true if and only if the grid node in the specified position is occupied by the head of a neighboring particle (for contracted particles, head and tail occupy the same node.)

IsMainColorSet()

Checks whether this particle's main color has been overwritten.

GetMainColor() only returns a meaningful value if this method returns true.

Declaration

public bool IsMainColorSet()

Returns

Type	Description
bool	true if and only if the particle's main color has been overwritten and has not been reset since.

IsTailAt(Direction, bool)

Checks if the part of the neighboring particle in the given local direction is the neighbor's tail. The position to check is determined in the same way as in HasNeighborAt(Direction, bool).

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation.

Declaration

public bool IsTailAt(Direction locDir, bool fromHead = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction from which to get the neighbor particle.
bool	fromHead	If true, look from the particle's head, otherwise look from the particle's tail (only relevant if this particle is expanded.)

Returns

Type	Description
bool	true if and only if the grid node in the specified position is occupied by the tail of a neighboring particle (for contracted particles, head and tail occupy the same node.)

MakeAnchor()

Turns this particle into the anchor of the system. The anchor particle defines the movement of the whole system during joint movements by keeping its global position.

If multiple particles call this method or MakeObjectAnchor(Direction, bool) in the same activation, the one that is activated last will become the anchor.

Declaration

public void MakeAnchor()

MakeObjectAnchor(Direction, bool)

Turns the neighboring object in the indicated direction into the anchor of the system.

If multiple particle call this method or MakeAnchor() in the same activation, the particle that is activated last will determine the anchor.

Declaration

public void MakeObjectAnchor(Direction d, bool fromHead = true)

Parameters

Type	Name	Description
Direction	d	The local direction in which the object neighbor lies.
bool	fromHead	Whether the neighboring object is at this particle's head (only relevant for expanded particles).

MarkBond(Direction, bool)

Marks the specified bond to have special behavior. This means that it will be pulled with an expansion movement if it does not point in the opposite direction as the movement. The bond pointing in the same direction as the movement will always be marked automatically. Only works in ActivateMove().

Declaration

public void MarkBond(Direction locDir, bool head = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction into which the bond is pointing.
bool	head	If the particle is expanded, this flag indicates whether the bond is located at the head or the tail.

PullHandover(bool, Direction)

Wrapper for PullHandoverHead(Direction) and PullHandoverTail(Direction) where the contraction target is specified as parameter head.

Note that movements are only applied at the end of a round, i.e., after the activation is over. This means that calling this method will have no immediate effect.

See also PushHandover(Direction), PullHandoverHead(Direction), PullHandoverTail(Direction).

Declaration

public void PullHandover(bool head, Direction locDir)

Parameters

Type	Name	Description
bool	head	If true, perform a head contraction, otherwise perform a tail contraction.
Direction	locDir	The local direction relative to this particle's head/tail from which the contracted neighbor particle should be pulled.

PullHandoverHead(Direction)

Contracts this particle into the grid node that is currently occupied by the particle's head while the contracted neighbor particle in the specified direction expands onto the current tail node. After the contraction, the head and tail of this particle will both occupy the current head node and the current tail node will be occupied by the neighbor. Only works in ActivateMove().

Only allowed if there is a contracted particle in the specified direction relative to this particle's tail that simultaneously performs a push handover.

Note that movements are only applied at the end of a round, i.e., after the activation is over. This means that calling this method will have no immediate effect.

See also PushHandover(Direction), ContractHead(), PullHandoverTail(Direction).

Declaration

public void PullHandoverHead(Direction locDir)

Parameters

Type	Name	Description
Direction	locDir	The local direction relative to this particle's tail from which the contracted neighbor particle should be pulled.

PullHandoverTail(Direction)

Contracts this particle into the grid node that is currently occupied by the particle's tail while the contracted neighbor particle in the specified direction expands onto the current head node. After the contraction, the head and tail of this particle will both occupy the current tail node and the current head node will be occupied by the neighbor. Only works in ActivateMove().

Only allowed if there is a contracted particle in the specified direction relative to this particle's head that simultaneously performs a push handover.

Note that movements are only applied at the end of a round, i.e., after the activation is over. This means that calling this method will have no immediate effect.

See also PushHandover(Direction), ContractTail(), PullHandoverHead(Direction).

Declaration

public void PullHandoverTail(Direction locDir)

Parameters

Type	Name	Description
Direction	locDir	The local direction relative to this particle's head from which the contracted neighbor particle should be pulled.

PushHandover(Direction)

Expands this particle in the specified local direction while the expanded neighbor particle in that direction contracts. After the expansion, the particle's head will occupy the grid node in that direction, and its tail will remain at its current position. The neighbor will have contracted away from that node. Only works in ActivateMove().

Only allowed if there is an expanded particle in the specified direction that simultaneously performs a pull handover aimed at this particle.

Note that movements are only applied at the end of a round, i.e., after the activation is over. This means that calling this method will have no immediate effect.

See also Expand(Direction), PullHandoverHead(Direction), PullHandoverTail(Direction).

Declaration

public void PushHandover(Direction locDir)

Parameters

Type	Name	Description
Direction	locDir	The local direction into which the particle should expand.

ReceivedBeepOnPartitionSet(int)

Checks whether the specified partition set has received a beep in the last round.

Declaration

public bool ReceivedBeepOnPartitionSet(int partitionSetID)

Parameters

Type	Name	Description
int	partitionSetID	The ID of the partition set to check.

Returns

Type	Description
bool	true if and only if the partition set with ID partitionSetID has received a beep.

ReceivedBeepOnPin(Direction, int, bool)

Checks whether the specified pin has received a beep in the last round.

Declaration

public bool ReceivedBeepOnPin(Direction direction, int offset, bool head = true)

Parameters

Type	Name	Description
Direction	direction	The direction of the edge containing the pin.
int	offset	The pin offset on the specified edge. Must be in the range 0,...,PinsPerEdge-1.
bool	head	If the particle is expanded, use this flag to indicate whether the edge belongs to the particle's head or not.

Returns

Type	Description
bool	true if and only if the specified pin has received a beep.

ReceivedMessageOnPartitionSet(int)

Checks whether the specified partition set has received a message in the last round.

Declaration

public bool ReceivedMessageOnPartitionSet(int partitionSetID)

Parameters

Type	Name	Description
int	partitionSetID	The ID of the partition set to check.

Returns

Type	Description
bool	true if and only if the partition set with ID partitionSetID has received a message.

ReceivedMessageOnPin(Direction, int, bool)

Checks whether the specified pin has received a message in the last round.

The direction of the edge containing the pin. The pin offset on the specified edge. Must be in the range 0,...,PinsPerEdge-1. If the particle is expanded, use this flag to indicate whether the edge belongs to the particle's head or not. true if and only if the specified pin has received a message.

Declaration

public bool ReceivedMessageOnPin(Direction direction, int offset, bool head = true)

Parameters

Type	Name	Description
Direction	direction
int	offset
bool	head

Returns

Type	Description
bool

ReleaseBond(Direction, bool)

Marks the specified bond to be released before the scheduled movement. Only works in ActivateMove().

Declaration

public void ReleaseBond(Direction locDir, bool head = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction into which the bond is pointing.
bool	head	If the particle is expanded, this flag indicates whether the bond is located at the head or the tail.

ResetMainColor()

Resets the particle's main color to its default value. The color will be shown as soon as the round computation is finished.

Declaration

public void ResetMainColor()

SendBeepOnPartitionSet(int)

Sends a beep on the specified partition set.

Declaration

public void SendBeepOnPartitionSet(int partitionSetID)

Parameters

Type	Name	Description
int	partitionSetID	The ID of the partition set on which to send the beep.

SendBeepOnPin(Direction, int, bool)

Sends a beep on the specified pin.

Declaration

public void SendBeepOnPin(Direction direction, int offset, bool head = true)

Parameters

Type	Name	Description
Direction	direction	The direction of the edge containing the pin.
int	offset	The pin offset on the specified edge. Must be in the range 0,...,PinsPerEdge-1.
bool	head	If the particle is expanded, use this flag to indicate whether the edge belongs to the particle's head or not.

SendMessageOnPartitionSet(int, Message)

Sends the given message on the specified partition set.

Note that a copy of the given Message instance msg is sent. Altering the instance after calling this method has no effect on the sent message.

Declaration

public void SendMessageOnPartitionSet(int partitionSetID, Message msg)

Parameters

Type	Name	Description
int	partitionSetID	The ID of the partition set on which to send the message.
Message	msg	The message to be sent.

SendMessageOnPin(Direction, int, Message, bool)

Sends the given message on the specified pin.

Note that a copy of the given Message instance msg is sent. Altering the instance after calling this method has no effect on the sent message.

Declaration

public void SendMessageOnPin(Direction direction, int offset, Message msg, bool head = true)

Parameters

Type	Name	Description
Direction	direction	The direction of the edge containing the pin.
int	offset	The pin offset on the specified edge. Must be in the range 0,...,PinsPerEdge-1.
Message	msg	The message to be sent.
bool	head	If the particle is expanded, use this flag to indicate whether the edge belongs to the particle's head or not.

SetMainColor(Color)

Sets the main color of this particle. The color will be displayed as soon as the round computation is finished.

Declaration

public void SetMainColor(Color c)

Parameters

Type	Name	Description
Color	c	The color to be applied to the particle.

SetNextPinConfiguration(PinConfiguration)

Sets the pin configuration that should be applied to the particle at the end of this round. Only works in ActivateBeep().

The expansion state of the pin configuration must match the expansion state of the particle, i.e., if the particle is contracted, the pin configuration must be made for the contracted state, and if the particle is expanded, the pin configuration must match the corresponding head direction.

If no pin configuration is set in the same round in which a movement is performed, the pin configuration defaults to the singleton pattern. If no movement and no new pin configuration are planned, the configuration is left unchanged.

Declaration

public void SetNextPinConfiguration(PinConfiguration pinConfiguration)

Parameters

Type	Name	Description
PinConfiguration	pinConfiguration	The pin configuration to be applied at the end of the current round.

SetPlannedPinConfiguration(PinConfiguration)

Sets the pin configuration that should be applied to the particle at the end of this round. Only works in ActivateBeep().

The expansion state of the pin configuration must match the expansion state of the particle, i.e., if the particle is contracted, the pin configuration must be made for the contracted state, and if the particle is expanded, the pin configuration must match the corresponding head direction.

If no pin configuration is planned in the same round in which a movement is performed, the pin configuration defaults to the singleton pattern. If no movement and no new pin configuration are planned, the configuration is left unchanged.

Declaration

[Obsolete("This method is part of the old pin configuration system. To overwrite the next pin configuration, call SetNextPinConfiguration.")]
public void SetPlannedPinConfiguration(PinConfiguration pinConfiguration)

Parameters

Type	Name	Description
PinConfiguration	pinConfiguration	The pin configuration to be applied at the end of the current round.

ShowBond(Direction, bool)

Shows the bond at the given label if it has previously been hidden.

See HideBond(Direction, bool), IsBondVisible(Direction, bool).

Declaration

public void ShowBond(Direction locDir, bool head = true)

Parameters

Type	Name	Description
Direction	locDir	The local direction into which the bond is pointing.
bool	head	If the particle is expanded, this flag indicates whether the bond is located at the head or the tail

TailDirection()

Returns the local direction pointing from the particle's head towards its tail.

Note: This method returns information from the snapshot taken at the beginning of the current round. Its return value will not change during this activation. Use TailDirection_After() to get the predicted value for after the round.

Declaration

public Direction TailDirection()

Returns

Type	Description
Direction	The local direction pointing from the particle's head towards its tail, if it is expanded, otherwise -1.

TailDirection_After()

Like TailDirection(), but returns the predicted value for after the round.

Declaration

public Direction TailDirection_After()

Returns

Type	Description
Direction	The local direction pointing from the particle's head towards its tail, if it is expanded, otherwise -1.

TriggerObjectBondRelease(Direction, bool)

Makes the neighboring object in the indicated direction release all of its bonds to other objects in the current round. Can only be called in the movement phase.

Declaration

public void TriggerObjectBondRelease(Direction d, bool fromHead = true)

Parameters

Type	Name	Description
Direction	d	The local direction in which the object neighbor lies.
bool	fromHead	Whether the neighboring object is at this particle's head (only relevant for expanded particles).

UseAutomaticBonds()

Switches to automatic bond mode, causing the movements of the particle to behave like in the original model without joint movements.

Any changes made to the bond setup will be overwritten by the automatic bonds. Setting this mode will also avoid warning messages caused by disagreeing bonds. Only works in ActivateMove().

Note that joint movements are not disabled completely by this method. For example, expanding into another particle will result in pushing the neighbor away if it causes no conflict.

Declaration

public void UseAutomaticBonds()