# Simulator User Interface

pypdevs.simulator.loadCheckpoint(name)

  Load a previously created simulation from a saved checkpoint.

  Parameters

    name – the name of the model to provide some distinction between different simulation models

  Returns

    either None if no recovery was possible, or the Simulator object after simulation

class pypdevs.simulator.Simulator(model)

  Associates a hierarchical DEVS model with the simulation engine.

  __init__(model)

    Constructor of the simulator.

    Parameters

      model – a valid model (created with the provided functions)

  simulate()

    Start simulation with the previously set options. Can be reran afterwards to continue the simulation of the model (or reinit it first and restart simulation), possibly after altering some aspects of the model with the provided methods.

All configuration of the simulator is forwarded to the Simulator Configuration class. These methods can simply be invoked on a Simulator object.

class pypdevs.simconfig.SimulatorConfiguration(sim)

  All necessary simulator configuration options are provided. The necessary checks will be made and the simulator will be adapted accordingly.

  __init__(sim)

    Constructor

    Parameters

      sim – the simulator to alter with actions on this configurator

  registerState(variable, model)

    Registers the state of a certain model to an attribute of the simulator AFTER simulation has finished

    Parameters

      - variable – name of the attribute to assign to

      - model – the AtomicDEVS model or its model id to fetch the state from

  setActivityRelocatorBasicBoundary(swappiness)

    Sets the use of the activity relocator called ‘Basic Boundary’.

    Parameters

      swappiness – how big the deviation from the average should be before scheduling relocations

  setActivityRelocatorCustom(filename, classname, *args)

    Sets the use of a custom relocator

    Parameters

      - filename – filename containing the relocator

      - classname – classname of the relocator

      - args – all other args are passed to the constructor

  setActivityTrackingVisualisation(visualize, x=0, y=0)

    Set the simulation to visualize the results from activity tracking. An x and y parameter can be given to visualize it in a cell style.

    Parameters

      - visualize – whether or not to visualize it

      - x – the horizontal size of the grid (optional)

      - y – the vertical size of the grid (optional)

  setAllowLocalReinit(allowed=True)

    Allow a model to be reinitialized in local simulation. This is not the case by default, as it would be required to save a copy of the model in memory during setup. Generating such a copy can be time consuming and the additional memory consumption could be unacceptable. Distributed simulation is unaffected, since this always requires the creation of a copy. If this is False and reinitialisation is done in a local simulation, an exception will be thrown.

    Warning

    The state that is accessible after the simulation will NOT be updated if this configuration parameter is used. If you want to have fully up to date states, you should also set the setFetchAllAfterSimulation() configuration parameter.

    Parameters

      allowed – whether or not to allow reinitialization

  setAutoAllocator()

    Sets the use of an initial allocator that simply distributes the root models. This is a static allocator, meaning that no event activity will be generated.

  setCell(x_size=None, y_size=None, cell_file='celltrace', multifile=False)

    Sets the cell tracing flag of the simulation

    Parameters

      - cell – whether or not verbose output should be generated

      - x_size – the horizontal length of the grid

      - y_size – the vertical length of the grid

      - cell_file – the file to save the generated trace to

      - multifile – if True, each timestep will be save to a seperate file (nice for visualisations)

  setCheckpointing(name, checkpoint_interval)

    Warning

    name parameter will be used as a filename, so avoid special characters

    Sets the interval between 2 checkpoints in terms of GVT calculations. This option generates PDC files starting with ‘name’. This is only possible when using MPI.

    Parameters

      - name – name to prepend to each checkpoint file

      - checkpoint_interval – number of GVT runs that are required to trigger a checkpoint. For example 3 means that a checkpoint will be created after each third GVT calculation

  setClassicDEVS(classicDEVS=True)

    Use Classic DEVS instead of Parallel DEVS. This option does not affect the use of Dynamic Structure DEVS or realtime simulation. Not usable with distributed simulation.

    Parameters

      classicDEVS – whether or not to use Classic DEVS

  setCustomTracer(tracerfile, tracerclass, args)

    Sets the use of a custom tracer, loaded at run time.

    Calling this function multiple times will register a tracer for each of them (thus output to multiple files is possible, though more inefficient than simply (manually) copying the file at the end).

    Parameters

      - tracerfile – the file containing the tracerclass

      - tracerclass – the class to instantiate

      - args – arguments to be passed to the tracerclass’s constructor

  setDSDEVS(dsdevs=True)

    Whether or not to enable Dynamic Structure DEVS simulation. If this is set to True, the modelTransition method will be called on all transitioned models. If this is False, the modelTransition method will not be called, even if one is defined! Enabling this incurs a (slight) slowdown in the simulation, due to the additional function calls and checks that have to be made. Currently only available in local simulation.

    Parameters

      dsdevs – enable or not

  setDrawModel(draw_model=True, output_file='model.dot', hide_edge_labels=False)

    Whether or not to draw the model and its distribution before simulation starts.

    Parameters

      - draw_model – whether or not to draw the model

      - output_file – file to output to

      - hide_edge_labels – whether or not to hide the labels of the connections, this speeds up the model drawing and allows for reasonably sized diagrams

  setFetchAllAfterSimulation(fetch=True)

    Update the complete model by fetching all states from all remote locations. This is different from ‘registerState’, as it will fetch everything and it will modify the original model instead of adding an attribute to the Simulator object

    Parameters

      fetch – whether or not to fetch all states from all models

  setGVTInterval(gvt_int)

    Sets the interval in seconds between 2 GVT calculations. This is the time between the ending of the previous run and the start of the next run, to prevent overlapping calculations.

    Note

    Parameter should be at least 1 to prevent an overload of GVT calculations

    Parameters

      gvt_int – interval in seconds (float or integer)

  setGreedyAllocator()

    Sets the use of the greedy allocator that is contained in the standard PyPDEVS distribution.

  setInitialAllocator(allocator)

    Sets the use of an initial allocator instead of the manual allocation. Can be set to None to use manual allocation (default).

    Parameters

      allocator – the allocator to use for assigning the initial locations

  setListenPorts(port, function)

    Sets a listener on a DEVS port. When an event arrives at that output port, the provided function will be called with the bag (as if that function were the extTransition!).

    Listening to ports is only allowed in realtime simulation! Remember to return from the calling function as soon as possible to minimize delays. Only a single listener is supported per port.

    Parameters

      - port – the port to listen to, can be anything.

      - function – the function to call when the event arrives. It should take a single parameter (the event bag).

  setLocationCellMap(locationmap, x=0, y=0)

    Set the simulation to produce a nice Cell DEVS like output file of the current location. This file will be regenerated as soon as some relocations are processed.

    Parameters

      - locationmap – whether or not to generate this file

      - x – the horizontal size of the grid

      - y – the vertical size of the grid

  setLogging(destination, level)

    Sets the logging destination for the syslog server.

    Parameters

      - destination – A tuple/list containing an address, port pair defining the location of the syslog server. Set to None to prevent modification

      - level – the level at which logging should happen. This can either be a logging level from the logging module, or it can be a string specifying this level. Accepted strings are: ‘debug’, ‘info’, ‘warning’, ‘warn’, ‘error’, ‘critical’

  setManualRelocator()

    Sets the use of the manual relocator (the default). This mode allows the user to add manual relocation directives.

  setMemoization(memo=True)

    Use memoization to prevent repeated int/ext/confTransition calls when revertion was performed.

    Parameters

      memo – enable or not

  setMessageCopy(copy_method)

    Sets the type of message copying to use, this will have an impact on performance. It is made customizable as some more general techniques will be much slower.

    Parameters

      copy_method – Either an ID of the option, or (recommended) a string specifying the method, see options below

    pickle

      use the (c)pickle module

    custom

      define a custom ‘copy’ function in every message and use this

    none

      don’t use any copying at all, unsafe though most other DEVS simulators only supply this

  setModelAttribute(model, attr, value)

    Reinitialize an attribute of the model itself

    Calling this method will cause a recomputation of the timeAdvance for this model. Its results will be used relative to the time of the last transition.

    Parameters

      - model – model whose attribute to set

      - attr – string representation of the attribute to change

      - value – value to assign

  setModelState(model, new_state)

    Reinitialize the state of a certain model

    Calling this method will cause a recomputation of the timeAdvance for this model. Its results will be used relative to the time of the last transition.

    Parameters

      - model – model whose state to change

      - new_state – state to assign to the model

  setModelStateAttr(model, attr, value)

    Reinitialize an attribute of the state of a certain model

    Calling this method will cause a recomputation of the timeAdvance for this model. Its results will be used relative to the time of the last transition.

    Parameters

      - model – model whose state to change

      - attr – string representation of the attribute to change

      - value – value to assign

  setRealTime(realtime=True, scale=1.0)

    Sets the use of realtime instead of ‘as fast as possible’.

    Parameters

      - realtime – whether or not to use realtime simulation

      - scale – the scale for scaled real time, every delay will be multiplied with this number

  setRealTimeInputFile(generator_file)

    Sets the realtime input file to use. If realtime is not yet set, this will auto-enable it.

    Parameters

      generator_file – the file to use, should be a string, NOT a file handle. None is acceptable if no file should be used.

  setRealTimePlatformGameLoop()

    Sets the realtime platform to Game Loop. If realtime is not yet set, this will auto-enable it.

    Parameters

      fps – the number of times the game loop call should be made per second

  setRealTimePlatformThreads()

    Sets the realtime platform to Python Threads. If realtime is not yet set, this will auto-enable it.

  setRealTimePlatformTk(tk)

    Note

    this clearly requires Tk to be present.

    Sets the realtime platform to Tk events. If realtime is not yet set, this will auto-enable it.

  setRealTimePorts(ports)

    Sets the dictionary of ports that can be used to put input on. If realtime is not yet set, this will auto-enable it.

    Parameters

      ports – dictionary with strings as keys, ports as values

  setRelocationDirective(time, model, destination)

    Creates a relocation directive, stating that a relocation of a certain model should happen at or after the specified time (depending on when the GVT progresses over this time).

    If multiple directives exist for the same model, the one with the highest time will be executed.

    Parameters

      - time – time after which the relocation should happen

      - model – the model to relocate at the specified time. Can either be its ID, or an AtomicDEVS or CoupledDEVS model. Note that providing a CoupledDEVS model is simply a shortcut for relocating the COMPLETE subtree elsewhere, as this does not stop at kernel boundaries.

      - destination – the location to where the model should be moved

  setRelocationDirectives(directives)

    Sets multiple relocation directives simultaneously, easier for batch processing. Behaviour is equal to running setRelocationDirective on every element of the iterable.

    Parameters

      directives – an iterable containing all directives, in the form [time, model, destination]

  setRemoveTracers()

    Removes all currently registered tracers, might be useful in reinitialised simulation.

  setSchedulerActivityHeap(locations=None)

    Use the basic activity heap scheduler, this is the default.

    Parameters

      locations – if it is an iterable, the scheduler will only be applied to these locations. If it is None, all nodes will be affected.

  setSchedulerCustom(filename, scheduler_name, locations=None)

    Use a custom scheduler

    Parameters

      - filename – filename of the file containing the scheduler class

      - scheduler_name – class name of the scheduler contained in the file

      - locations – if it is an iterable, the scheduler will only be applied to these locations. If it is None, all nodes will be affected.

  setSchedulerDirtyHeap(locations=None)

    Use the basic activity heap scheduler, but without periodic cleanup. The same scheduler as the one used in VLE.

    Parameters

      locations – if it is an iterable, the scheduler will only be applied to these locations. If it is None, all nodes will be affected.

  setSchedulerDiscreteTime(locations=None)

    Use a basic ‘discrete time’ style scheduler. If the model is scheduled, it has to be at the same time as all other scheduled models. It isn’t really discrete time in the sense that it allows variable step sizes, only should ALL models agree on it.

    Parameters

      locations – if it is an iterable, the scheduler will only be applied to these locations. If it is None, all nodes will be affected.

    Warning

    Only use in local simulation!

  setSchedulerHeapSet(locations=None)

    Use a scheduler containing 3 different datastructures. It is still experimental, though can provide noticeable performance boosts.

    Parameters

      locations – if it is an iterable, the scheduler will only be applied to these locations. If it is None, all nodes will be affected.

  setSchedulerMinimalList(locations=None)

    Use a simple scheduler that keeps a list of all models and traverses it each time in search of the first one. Slight variation of the sorted list scheduler.

    Parameters

      locations – if it is an iterable, the scheduler will only be applied to these locations. If it is None, all nodes will be affected.

  setSchedulerNoAge(locations=None)

    Warning

    do not use this scheduler if the time advance can be equal to 0. This scheduler strips of the age from every scheduled model, which means that ages do not influence the scheduling.

    Use a stripped scheduler that doesn’t care about the age in a simulation. It is equivalent in design to the HeapSet scheduler, but uses basic floats instead of tuples.

    Parameters

      locations – if it is an iterable, the scheduler will only be applied to these locations. If it is None, all nodes will be affected.

  setSchedulerPolymorphic(locations=None)

    Use a polymorphic scheduler, which chooses at run time between the HeapSet scheduler or the Minimal List scheduler. Slight overhead due to indirection and statistics gathering.

    Warning

    Still unstable, don’t use!

    Parameters

      locations – if it is an iterable, the scheduler will only be applied to these locations. If it is None, all nodes will be affected.

  setSchedulerSortedList(locations=None)

    Use an extremely simple scheduler that simply sorts the list of all models. Useful if lots of invalidations happen and nearly all models are active.

    Parameters

      locations – if it is an iterable, the scheduler will only be applied to these locations. If it is None, all nodes will be affected.

  setShowProgress(progress=True)

    Shows progress in ASCII in case a termination_time is given

    Parameters

      progress – whether or not to show progress

  setStateSaving(state_saving)

    Sets the type of state saving to use, this will have a high impact on performance. It is made customizable as some more general techniques will be much slower, though necessary in certain models.

    Parameters

      state_saving – Either an ID of the option, or (recommended) a string specifying the method, see options below.

    deepcopy

      use the deepcopy module

    pickle0

      use the (c)pickle module with pickling protocol 0

    pickleH

      use the (c)pickle module with the highest available protocol

    pickle

      use the (c)pickle module

    copy

      use the copy module (only safe for flat states)

    assign

      simply assign states (only safe for primitive states)

    none

      equivalent to assign (only safe for primitive states)

    custom

      define a custom ‘copy’ function in every state and use this

  setTerminationCondition(condition)

    Sets the termination condition for the simulation. Setting this will remove a previous termination time and condition. This condition will be executed on the controller

    Parameters

      condition – a function to call that returns a boolean whether or not to halt simulation

  setTerminationModel(model)

    Marks a specific AtomicDEVS model as being used in a termination condition. This is never needed in case no termination_condition is used. It will _force_ the model to run at the controller, ignoring the location that was provided in the model itself. Furthermore, it will prevent the model from migrating elsewhere.

    Parameters

      model – an AtomicDEVS model that needs to run on the controller and shouldn’t be allowed to migrate

  setTerminationTime(time)

    Sets the termination time for the simulation. Setting this will remove a previous termination time and condition.

    Parameters

      time – time at which simulation should be halted

  setVCD(filename)

    Sets the use of a VCD tracer.

    Calling this function multiple times will register a tracer for each of them (thus output to multiple files is possible, though more inefficient than simply (manually) copying the file at the end).

    Parameters

      filename – string representing the filename to write the trace to

  setVerbose(filename=None)

    Sets the use of a verbose tracer.

    Calling this function multiple times will register a tracer for each of them (thus output to multiple files is possible, though more inefficient than simply (manually) copying the file at the end).

    Parameters

      filename – string representing the filename to write the trace to, None means stdout

  setXML(filename)

    Sets the use of a XML tracer.

    Calling this function multiple times will register a tracer for each of them (thus output to multiple files is possible, though more inefficient than simply (manually) copying the file at the end).

    Parameters

      filename – string representing the filename to write the trace to