How to create a coupling-artefact in order to exchange one kind of data

Example with a Netlogo random walk model


The model used is a simple random walk where, for each simulation step, agents (so-called walkers) choose a random direction and step forward. The Netlogo model specification is available here. The exchanged data will be here the walkers positions (x,y) the same for input and output. In this simplistic case, the model exchange theses data with itself (i.e. its input port correspond to its output port). Since not very useful for simulation results, this example allows to introduce the very first concepts and their implementation.

In this tutorial, we present the implementation of the coupling-artefact (which role is to allow the model-agent to exchange some data and take operations on the data flow).

random walk example 1

Creating a coupling-artefact

In order to create a coupling-artefact, you need to understand that a coupling-artefact is made of input port (one and only one) and output ports (one or several). Here in our example, we define a coupling artefact made of an input port and an output port both accepting the walker position data.

The coupling-artefact input port


The role of coupling-artefact input port is allow model-agent to post the data (from the model to the external world). In order to build a coupling-artefact input port, you need to extend the abstract calls InputPort. An important thing to note is that each coupling-artefact port is dedicated to a certain class. In our example, we want to post data of class TurtlePositions.

Since our implementation (darjeeling) relies upon Java Messaging Service (JMS), we need to provide some parameters in order for the input port to post the data to the JMS. These parameters are currently the topic name, and the connection factory name (for further details see LinkInstallJMS).

/**
 * This class represent one part (IN port) of the coupling artefact that allows
 * the agent to read data from it. In this implementation the coupling-artefact
 * is in charge of the agents positions.
 * 
 * @author Julien Siebert
 * @since Darjeeling
 */
public class IPCA_WalkerPositions extends InputPort<TurtlePositions> implements
    JmsPort {

  // jms parameters
  private String topicName;
  private String connectionFactoryName;
  // end of jms parameters

  /**
   * COnstructor
   */
  public IPCA_WalkerPositions(Class<TurtlePositions> ObjectClassToSendToJms,
      String NameOfInputPortToJms) {
    super(ObjectClassToSendToJms, NameOfInputPortToJms);
    setJMSConnexionParameters();
    init();
  }

  public void init() {
    try {
      jmsInputBinding.init(topicName, connectionFactoryName);
    } catch (NamingException e) {
      e.printStackTrace();
    } catch (JMSException e) {
      e.printStackTrace();
    }
  }

  public void setJMSConnexionParameters() {
    topicName = "shared_data";
    connectionFactoryName = "shared_data_topic_connection_factory";
  }
}

The coupling-artefact output port


The role of coupling-artefact output port is allow model-agent to read the external data. In order to build a coupling-artefact output port, you need to extend the abstract calls OutputPort. An important thing to note is that each coupling-artefact port is dedicated to a certain class. In our example, we want to read data of class TurtlePositions.

Since our implementation (darjeeling) relies upon Java Messaging Service (JMS), we need to provide some parameters in order for the output port to read the data from the JMS. These parameters are currently the topic name, and the connection factory name (for further details see LinkInstallJMS).

/**
 * This class represent one part (OUT port) of the coupling artefact that allows
 * the agent to read data from it. In this implementation the coupling-artefact
 * is in charge of the agents positions.
 * 
 * @author Julien Siebert
 * @since Darjeeling
 */
public class OPCA_WalkerPositions extends OutputPort<TurtlePositions> implements
    JmsPort {

  // jms parameters
  private String topicName;
  private String connectionFactoryName;
  // end of jms parameters

  /**
   * Constructor
   */
  public OPCA_WalkerPositions(Class<TurtlePositions> ObjectClassToReadFromJms,
      String NameOfOutputPortFromJms) {
    super(ObjectClassToReadFromJms, NameOfOutputPortFromJms);
    setJMSConnexionParameters();
    init();
  }

  public void init() {
    try {
      jmsOutputBinding.init(topicName, connectionFactoryName);
    } catch (NamingException e) {
      e.printStackTrace();
    } catch (JMSException e) {
      e.printStackTrace();
    }
  }

  public void setJMSConnexionParameters() {
    topicName = "shared_data";
    connectionFactoryName = "shared_data_topic_connection_factory";
  }
}

Creative Commons LicenseLogos and images provided by Agent and Artefacts for Multiple Models coordination is available under the terms of the following Creative Commons License. The source code is provided under the terms of the following CeCIll license.