j143-zz/sydevs

Simulation-based analysis of complex systems involving people, devices, physical elements, and dynamic environments.

SyDEVS

Multiscale Simulation and Systems Modeling Library

Windows	Linux/OSX

About

This library provides a framework for implementing complex systems analysis and simulation code in a modular/hierarchical fashion. The framework combines three modeling paradigms: discrete event simulation, agent-based modeling, and dataflow programming. The discrete event simulation aspect is based on DEVS, a well-regarded modeling formalism involving two types of models that correspond with the library's atomic and composite nodes. The library also includes collection nodes, which extend DEVS with agent-based modeling capabilities, and function nodes, which simply compute outputs from inputs. The atomic, composite, collection, and function nodes can communicate through flow ports as part of a dataflow programming network. With the exception of function nodes, they can also communicate in a DEVS-like fashion through message ports.

In addition to supporting multiple modeling paradigms, the SyDEVS library provides comprehensive and reusable Modern C++ implementations of multidimensional arrays, Standard International (SI) units, a multiscale time representation, and other technical computing elements.

The main SyDEVS website is at https://autodesk.github.io/sydevs.

Main Classes

The library includes C++11/14 classes grouped into three main folders:

src/sydevs/core

This folder contains generic classes that may be useful for a variety of applications.

• scale: Represents the general concept of scale as a dimensionless power of 1000.
  • number_types.h (related header file): Defines the constant pi and type aliases for integers and floating-point numbers.
• quantity: A data type template which represents a Standard International (SI) quantity (e.g. mass, distance, duration, acceleration) as a multiple of a base-1000 precision level.
  • units (related struct template): Represents SI units including the base units such as grams, meters, and seconds, and derived units such as meters-per-second-squared.
• identity: A data type which identifies an item by combining an encapsulated integer-valued index with a dimension supplied by a template parameter.
• arraynd: A multidimensional array with features similar to those of the NumPy Python Library.
  • range (related class): Represents a range of array indices along a single dimension.
• qualified_type: Traits for data types that can be passed among system nodes.
  • pointer (related class): Points to any type of data.
  • string_builder (related class): Faciliates value-to-string conversions.

src/sydevs/time

The classes in this folder implement the multiscale time representation proposed by Goldstein et al. (2017) that supports the recording and scheduling of events over any combination of short and long time scales. The classes below use 64-bit operations where possible despite accommodating extremely disparate scales.

• time_point: Represents a point in time as an arbitrary-precision multiple of its shortest time precision.
• time_sequence: Represents a sequence of increasing time points.
• time_queue: Supports the scheduling of future events.
• time_cache: Provides durations elapsed since past events.

src/sydevs/systems

This folder contains the elements from which dataflow + message-passing networks are constructed.

• system_node: A base class for all nodes.
  • atomic_node (derived from system_node): A base class for indivisible nodes in which simulation behavior is procedurally encoded.
  • composite_node (derived from system_node): A base class for all nodes defined as fixed-structure compositions of different types of nodes.
  • collection_node (derived from system_node): A base class for all nodes defined as variable-length collections of nodes of a single type.
  • function_node (derived from system_node): A base class for indivisible nodes in which function behavior is procedurally encoded.
    • parameter_node (derived from function_node): A function node template for supplying parameters.
    • statistic_node (derived from function_node): A function node template for retrieving statistics.
  • interactive_system (derived from collection_node): A base class template for all interactive closed system nodes intended to be used at the highest level of a real time simulation model.
  • port (related class): A base class for the four types of ports (flow input, message input, message output, flow output).
• simulation: Class template for simulations performed using a top-level (port-free) system node.
  • real_time_simulation (derived from simulation): A class template for running simulations in real time.
    • real_time_buffer (related class): A data structure which suggests event wallclock times to aid in the synchronization of a simulation's execution.
  • discrete_event_time (related class): Represents progress through a simulation, encapsulating both simulated time and a counter of events within a single point in simulated time.

Building

Building on Windows (Visual Studio)

• You will need CMake
• Make sure you have Visual Studio 2015 or Visual Studio 2017
• mkdir bin
• cd bin/
• cmake -G "Visual Studio 14 2015 Win64" .. or cmake -G "Visual Studio 15 2017 Win64" ..
• Open bin/SyDEVS.sln in Visual Studio
• Recommendation: In Tools -> Options -> Text Editor -> C/C++ -> Tabs, select Insert spaces with a Tab size and Indent size of 4

Building on Mac OS

• You will need CMake
• mkdir bin
• cd bin/
• cmake -G "Xcode" ..
• xcodebuild -project SyDEVS.xcodeproj or open the .xcodeproj file.

Testing

Unit and regression tests are run automatically during the build process.

The unit testing framework used in SyDEVS is Catch2. See the documentation for a tutorial and reference material. Catch2 is released under the Boost Software License 1.0.

Documentation

Website

Main SyDEVS website with Overview and Getting Started tutorial:

• https://autodesk.github.io/sydevs

HTML

Latest published version of the HTML documentation:

• https://autodesk.github.io/sydevs/doc/html/index.html

To build or update the documentation files with Doxygen make sure you are in the top level directory (where the doxygen.config is) and execute the following command:

• doxygen doxygen.config

This will build the documentation in the doc directory. To open the documentation:

• cd docs/html
• Open index.html in your web browser.

You should update the documentation on a regular basis to keep it in sync with the code.

PowerPoint

There are three PowerPoint documents located in the doc folder:

• SyDEVS_Introduction.pptx: An introduction to the theory, paradigm, and code associated with SyDEVS.
• SyDEVS_Framework_Overview.pptx: An overview of the systems modeling framework and related snippets of code.
• SyDEVS_Building7m_Tutorial.pptx: A tutorial that challenges developers to enhance the building7m example.

Examples

Examples of SyDEVS-based simulations are found in the src/examples directory.

The best examples for learning the library are those in demo.

In particular, the queueing project features one well-commented example of each of the four main types of nodes:

• queueing_node.h (atomic)
• two_stage_queueing_node.h (composite)
• parallel_queueing_node.h (collection)
• plus_node.h (function)

Contributing

Review the contributing guidelines before you consider working on SyDEVS and proposing contributions.

License

SPDX-License-Identifier: Apache-2.0