# BaseSimulator: the DEVS kernel

class pypdevs.basesimulator.BaseSimulator(name, model, server)

  The BaseSimulator class, this is the actual simulation kernel.

  __init__(name, model, server)

    Constructor

    Parameters

      - name – the name of the kernel

      - model – the model to initialise the kernel with

  activateModel(model_id, current_state)

    Activate the model at this kernel, thus allowing the kernel to use (and schedule) this model. Note that a revert to the GVT has to happen before calling this function, since the old_states are not transferred and thus reverting is impossible.

    Parameters

      - model_id – the id of the model that has to be activated

      - currentState – the current state of the model that gets migrated

  activateModels(bundle)

    Call the activateModel method on a list of arguments

    Parameters

      bundle – a bundle of messages to send, each entry should contain a tuple that can be expanded for the call

  check()

    Checks wheter or not simulation should still continue. This will either call the global time termination check, or the local state termination check, depending on configuration.

    Using the global time termination check is a lot FASTER and should be used if possible.

    Returns

      bool – whether or not to stop simulation

  checkpoint()

    Save a checkpoint of the current basesimulator, this function will assume that no messages are still left in the medium, since these are obviously not saved by pickling the base simulator.

  delayedAction(time, model_id, action)

    Perform an irreversible action (I/O, prints, global messages, …). All these actions will be performed in the order they should be generated in a non-distributed simulation. All these messages might be reverted in case a revertion is performed by the calling model.

    Parameters

      - time – the simulation time at which this command was requested

      - model_id – the model_id of the model that requested this command

      - action – the actual command to be executed as soon as it is safe

  finishAtTime(clock)

    Signal this kernel that it may stop at the provided time

    Parameters

      clock – the time to stop at

  finishRing(msg_sent, msg_recv, first_run=False)

    Go over the ring and ask each kernel whether it is OK to stop simulation or not. Uses a count to check that no messages are yet to be processed.

    Parameters

      - msg_sent – current counter for total amount of sent messages

      - msg_recv – current counter for total amount of received messages

      - first_run – whether or not to forward at the controller

    Returns

      int – amount of messages received and sent (-1 signals running simulation)

  genUUID()

    Create a unique enough ID for a message

    Returns

      string – a unique string for the specific name and number of sent messages

  getActivity(model_id)

    Returns the activity for a certain model id from the previous iteration

    Parameters

      model_id – the model_id to check

    Returns

      float – the activity

  getCompleteActivity()

    Returns the complete dictionary of all activities

    Returns

      dict – mapping of all activities

  getGVT()

    Return the GVT of this kernel

    Returns

      float – the current GVT

  getLocation(model_id)

    Returns the location at which the model with the provided model_id runs

    Parameters

      model_id – the model_id of the model of which the location is requested

    Returns

      int – the number of the kernel where the provided model_id runs

  getProxy(rank)

    Get a proxy to the specified rank.

    Method will simply forward the request to its server object.

    Parameters

      rank – the rank to return a proxy to

  getSelfProxy()

    Get a proxy to ourself.

    This method is useful in case the underlying code has no idea on which node it is running and it simply wants to contact its kernel. It also differs from simply calling the code on the object of the kernel, as this provides a wrapper for asynchronous local invocation.

  getState(model_id)

    Return the state of the specified model

    Parameters

      model_id – the model_id of the model of which the state is requested

    Returns

      state – the state of the requested model

  getStateAtTime(model_id, request_time)

    Gets the state of a model at a specific time

    Parameters

      - model_id – model_id of which the state should be fetched

      - request_time – time of the state

  getTime()

    Return the current time of this kernel

    Returns

      float – the current simulation time

  getTotalActivity(time=(inf, inf))

    Returns a dictionary containing the total activity through the complete simulation run

    Parameters

      time – time up to which to return activity

    Returns

      dict – mapping of all activities, but simulation-wide

  inits()

    Initialise the simulation kernel, this is split up from the constructor to make it possible to reset the kernel without reconstructing the kernel.

  loadCheckpoint()

    Alert this kernel that it is restoring from a checkpoint

  massDelayedActions(time, msgs)

    Call the delayedAction function multiple times in succession.

    Mainly implemented to reduce the number of round trips when tracing.

    Parameters

      - time – the time at which the action should happen

      - msgs – list containing elements of the form (model_id, action)

  messageTransfer(extraction)

    Transfer the messages during a model transfer

    Parameters

      extraction – the extraction generated by the messageScheduler

  migrateTo(destination, model_ids)

    Migrate all models to a new destination

    Parameters

      - destination – destination of all models specified hereafter

      - model_ids – iterable containing all models to migrate simultaneously

  migrationUnlock()

    Unlocks the simulation lock remotely.

    Warning

    do not use this function, unless you fully understand what you are doing!

  notifyMigration(model_ids, destination)

    Notify the migration of a model_id to a new destination

    Parameters

      - model_ids – the model_ids that gets moved

      - destination – the node location that now hosts the model_id

  notifyReceive(color)

    Notify the simulation kernel of the receiving of a message. Needed for GVT calculation.

    Parameters

      color – the color of the received message (for Mattern’s algorithm)

  notifySend(destination, timestamp, color)

    Notify the simulation kernel of the sending of a message. Needed for GVT calculation.

    Parameters

      - destination – the name of the simulation kernel that will receive the sent message

      - timestamp – simulation time at which the message is sent

      - color – color of the message being sent (for Mattern’s algorithm)

  performActions(gvt=inf)

    Perform all irreversible actions up to the provided time. If time is not specified, all queued actions will be executed (in case simulation is finished)

    Parameters

      gvt – the time up to which all actions should be executed

  processIncommingMessages()

    Process all incomming messages and return.

    This is part of the main simulation loop instead of being part of the message receive method, as we require the simlock for this. Acquiring the simlock elsewhere might take some time!

  processMessage(clock)

    Find the first external message smaller than the clock and process them if necessary. Return the new time_next for simulation.

    Parameters

      clock – timestamp of the next internal transition

    Returns

      timestamp of the next transition, taking into account external messages

  realtimeWait()

    Perform the waiting for input required in realtime simulation.

    The time_next of the model will be updated accordingly and all messages will be routed.

  receive(msg)

    Make the kernel receive the provided message.

    The method will return as soon as possible to prevent a big number of pending messages. Furthermore, acquiring the locks here would be impractical since we only process all incomming messages one at a time.

    Parameters

      msg – a NetworkMessage to process

  receiveAntiMessages(mintime, model_id, uuids, color)

    Process a (possibly huge) batch of anti messages for the same model

    Parameters

      - mintime – the lowest timestamp of all messages being cancelled

      - model_id – the model_id of the receiving model whose messages need to be negated, None to indicate a general rollback

      - uuids – list of all uuids to cancel

      - color – color for Mattern’s algorithm

    Note

    the model_id is only required to check whether or not the model is still local to us

  receiveControl(msg, first=False)

    Receive a GVT control message and process it. Method will block until the GVT is actually found, so make this an asynchronous call, or run it on a seperate thread.

    This code implements Mattern’s algorithm with a slight modification: it uses 4 different colours to distinguish two subsequent runs. Furthermore, it always requires 2 complete passes before a GVT is found.

  recomputeTA(model_id, time)

    Recompute the timeAdvance of a specific model and reapply it. It should only be called after the model was changed using one of the provided functions. The change will seemingly have happened right after the last simulation step, so your timeAdvance should NOT return something smaller than this. The actual absolute time_next will be determined at the time of the last transition too. If the model was not altered in a way that causes a major change to the state, the elapsed time attribute will take care of this call perfectly.

  removeActions(model_ids, time)

    Remove all actions specified by a model, starting from a specified time. This function should be called when the model is reverted and its actions have to be undone

    Parameters

      - model_ids – the model_ids of all reverted models

      - time – time up to which to remove all actions

  removeTracers()

    Removes all currently registered tracers. This does not clean them up, as this should already be done by the code at the end of the simulation.

  requestMigrationLock()

    Request this kernel to lock itself ASAP to allow a relocation to happen. This will invoke the notifyLocked method on the controller as soon as locking succeeded.

  resetSimulation(scheduler)

    Resets the simulation kernel to the saved version; can only be invoked after a previous simulation run.

    Parameters

      scheduler – the scheduler to set

  revert(time)

    Revert the current simulation kernel to the specified time. All messages sent after this time will be invalidated, all states produced after this time will be removed.

    Parameters

      time – the desired time for revertion.

    Note

    Clearly, this time should be >= the current GVT

  runsim()

    Run a complete simulation run. Can be run multiple times if this is required in e.g. a distributed simulation.

  send(model_id, timestamp, content)

    Prepare a message to be sent remotely and do the actual sending too.

    Parameters

      - model_id – the id of the model that has to receive the message

      - timestamp – timestamp of the message

      - content – content of the message being sent

  sendModel(model, model_ids, scheduler_type, flattened)

    Send a model to this simulation kernel, as this one will be simulated

    Parameters

      - model – the model to set

      - model_ids – list containing all models in order of their model_ids

      - scheduler_type – string representation of the scheduler to use

      - flattened – whether or not the model had its ports decoupled from the models to allow pickling

  setAttr(model_id, attr, value)

    Sets an attribute of a model.

    Parameters

      - model_id – the id of the model to alter

      - attr – string representation of the attribute to alter

      - value – value to set

  setGVT(gvt, activities, last_state_only)

    Sets the GVT of this simulation kernel. This value should not be smaller than the current GVT (this would be impossible for a correct GVT calculation). Also cleans up the input, output and state buffers used due to time-warp. Furthermore, it also processes all messages scheduled before the GVT.

    Parameters

      - gvt – the desired GVT

      - activities – the activities of all seperate nodes as a list

      - last_state_only – whether or not all states should be considered or only the last

  setGlobals(address, loglevel, checkpoint_frequency, checkpoint_name, statesaver, kernels, msg_copy, memoization, tracers)

    Configure all ‘global’ variables for this kernel

    Parameters

      - address – address of the syslog server

      - loglevel – level of logging library

      - checkpoint_frequency – frequency at which checkpoints should be made

      - checkpoint_name – name of the checkpoint to save

      - statesaver – statesaving method

      - kernels – number of simulation kernels in total

      - msg_copy – message copy method

      - memoization – use memoization or not

  setIrreversible()

    Mark this node as temporary irreversible, meaning that it can simply be made reversible later on. This can be used when all nodes are ran at a single node due to relocation, though future relocations might again move some nodes away.

  setStateAttr(model_id, attr, value)

    Sets an attribute of the state of a model

    Parameters

      - model_id – the id of the model to alter

      - attr – string representation of the attribute to alter

      - value – value to set

  setTerminationTime(time)

    Sets the time at which simulation should stop, setting this will override the local simulation condition.

    Parameters

      time – the time at which the simulation should stop

  simulate()

    Simulate at this kernel

  simulate_sync()

    A small wrapper around the simulate() function, though with a different name to allow a much simpler MPI one way check

  startTracers()

    Start all tracers

  stopTracers()

    Stop all tracers

  unsetIrreversible()

    Unmark this node as temporary irreversible.

  waitUntilOK(vector)

    Returns as soon as all messages to this simulation kernel are received. Needed due to Mattern’s algorithm. Uses events to prevent busy looping.

    Parameters

      vector – the vector number to wait for. Should be 0 for colors 0 and 1, should be 1 for colors 2 and 3.