Ensure the synchronization of the web client and the simulation engine.

Issue witnessed in commit: 52c5843

Issue description

The PRNG class from the extended libs was recently added a method to change the seed being used. Yet, as long as the implementation of the RNG is unknown to the user, simulations are not guaranteed to be reproducible, since the default RNG of PRNG might be changed in the future from XORO to Xoshiro256StarStar.

Therefore, PRNG should include a method telling which RNG is used in a readable format and, to facilitate simulation reproduction, a method loading such a RNG.

Issue location

Similar extended libs, class PRNG of package fr.univ_artois.lgi2a.similar.extendedkernel.libs.random

Possible solutions

1. Make get method public
   The most simple (an probably most unsuitable) method should be to switch the private static get( ) method to public, to grant access to the class instance of Random.

2. Create an export/import RNG feature
   Ideally, PRNG should provide two methods export():String and import(String) providing the expected facilitators:

   • The export method should convert the current RNG instance (instance static attribute) to a readable String containing all the relevant information for its construction. in practice, it probably will delegate the work to a method from the RNG class (maybe toString() ?)
   • The import method should parse a String obtained through export and convert it to a usable RNG instance. In practice, it probably delegate part of the work to an RNG constructor having a String argument, or to an initialize(String) method.

Issue witnessed in commit: 52c5843

Issue description

The documentation of Similar is currently in a web only format, with debatable looks (no offence intended towards its author) and is not up-to-date.

Solution

The HTML documentation embedded in the binary distribution should be:

1. Rewritten in Markdown
2. Updated with the last changes in similar (especially for the RNGs now included in the extended libs)
3. Moved to the wiki, since the repository manager does not intend to maintain parallel versions of the library

Issue witnessed in commit: 52c5843

Issue description

Probes cannot access neither the simulation parameters, nor the simulation model.

Issue location

In the interface ISimulationEngine (no such methods can be found).

Possible solutions

Add a wrapper for simulation engines, adding such methods :

public class ExtendedEngineWrapper implements ISimulationEngine {
   private AbstractExtendedSimulationModel model;
   private ISimulationEngine engine;
   public ExtendedEngineWrapper( ISimulationEngine engine ){
      this.engine = engine;
   }
   public runNewSimulation( AbstractExtendedSimulationModel model ){
      this.model = (AbstractExtendedSimulationModel) model:
      this.engine.runNewSimulation( model );
   }
   public runNewSimulation( ISimulationModel model ){
      if( ! ( model instanceof AbstractExtendedSimulationModel ) )
          throw IllegalArgumentException( "The model is not an instance of AbstractExtendedSimulationModel" );
      this.runNewSimulation( (AbstractExtendedSimulationModel) model ):
   }
   public ISimulationParameters getParameters() {
      if( this.model == null ) {
         throw new IllegalStateException( "The engine has no model" );
      }
      return this.model.getParameters();
   }
  //... Plus an implementation of all other methods of ISimulationEngine, calling the corresponding
  // method of this.engine
}

Edit: A proper implementation can be found here. Note that it does not work appropriately (see the comments below).

Preamble

Two types of initialization process for a simulation have been identified :

• As a brand new simulation, which model an initial state is built using the data obtained from the methods createLevels, createEnvironment and createAgents of the ISimulationModel interface

• Resuming an ended simulation (the state of such a simulation is directly extracted from the engine, without have to go through the methods of the ISimulationModel interface). Such an approach can also be used to run the clone of an existing and running simulation.

Issue

The current implementation of simulation engines are able to support the first case, but cannot support the second because the public local state of the environment and of the agents are already been added to the levels.

Moreover, the current initialization process will trigger the custom reaction to system influences for any level where the agent lies. This might lead to the multiple presence of an agent in collections inside the public local state of the environment. For instance, in road traffic simulations, a vehicle will appear twice in a lane :

• First because in the original state of the simulation, the vehicle was already in that lane
• Then because the current initialization process delegates the addition of the initial agents to their levels to new AddAgentToLevel system influences (and the system reaction)

Possible solution

The root interface of simulation engine should take into account such cases. For that purpose :

• A new type of simulation model should be created (for instance ClonedStateSimulationModel)
• ISimulationEngine should provide another runNewSimulation method for such models.
• The code of existing engines should be refactored to take into account this change. It should only require some minor refactoring inside the class AbstractSimulationEngineWithInitialization

Requirements: For this approach to work, it has to be possible to create a deep clone (i.e. a full clone managing appropriately cross references and immutable objects) of a simulation.

Bug witnessed in commit: c0f5455

Bug description

Creating instances of the RandomXoshiro256StarStar random number generator while providing a seed parameter throws an exception.

Error description

Source code:

RandomXoshiro256StarStar random = new RandomXoshiro256StarStar( 1000l );

Exception thrown:

java.lang.NullPointerException
	at fr.univ_artois.lgi2a.similar.extendedkernel.libs.random.rng.RandomXoshiro256StarStar.setSeed(RandomXoshiro256StarStar.java:58)
	at java.util.Random.<init>(Random.java:141)
	at fr.univ_artois.lgi2a.similar.extendedkernel.libs.random.rng.RandomXoshiro256StarStar.<init>(RandomXoshiro256StarStar.java:35)

The error also appears when:

• Calling the RandomXoshiro256StarStar() constructor;
• Calling the RandomGeneratorWrapper(String,long) constructor of class RandomGeneratorWrapper, using RandomGeneratorWrapper.XOROSHIRO_256 as the first parameter.

Environment

Environment where the bug occurred :

• Eclipse version 2018-12 (4.10.0) - Build id: 20181214-0600
• Java :
  • OpenJDK Runtime Environment (build 1.8.0_191-8u191-b12-0ubuntu0.18.04.1-b12)
  • OpenJDK 64-Bit Server VM (build 25.191-b12, mixed mode)
• Ubuntu 18.04 LTS

Possible cause

Line 55 of RandomXoshiro256StarStar defines the setSeed method as :

public void setSeed(long seed) {
		super.setSeed(seed);
		long sms = splitmix64_1(seed);
		s[0] = splitmix64_2(sms);
		sms = splitmix64_1(sms);
		s[1] = splitmix64_2(sms);
		sms = splitmix64_1(sms);
		s[2] = splitmix64_2(sms);
		sms = splitmix64_1(sms);
		s[3] = splitmix64_2(sms);
}

The error seems to be caused by the non initalization of the array s. Yet, it seems initialized later, at line 144 :

private final long[] s = new long[4];