pyjevsim 1.0.0__tar.gz

pyjevsim-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 eventsim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyjevsim-1.0.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include pyjevsim *.py
+recursive-exclude tests *
+recursive-exclude examples *
+recursive-exclude docs *
+recursive-exclude utils *
+recursive-exclude venv *
+exclude setup.py
+global-exclude *.pyc
+global-exclude __pycache__

pyjevsim-1.0.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.1
+Name: pyjevsim
+Version: 1.0.0
+Summary: A DEVS(Discrete Event System Specification) Modeling & Simulation environment with journaling functionality
+Home-page: https://github.com/eventsim/pyevsim
+Author: Changbeom Choi
+Author-email: Changbeom Choi <me@cbchoi.info>
+License: MIT
+Project-URL: Homepage, https://github.com/eventsim/pyjevsim
+Project-URL: Documentation, https://pyjevsim.readthedocs.io/en/latest/index.html
+Project-URL: Repository, https://github.com/eventsim/pyjevsim
+Project-URL: Issues, https://github.com/eventsim/pyjevsim/issues
+Keywords: DEVS,simulation,discrete-event,modeling
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: snapshot
+Requires-Dist: dill>=0.3.6; extra == "snapshot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: dill>=0.3.6; extra == "dev"
+
+# pyjevsim
+## Introduction
+pyjevsim is a DEVS(discrete event system specification) environment that provides journaling functionality.
+It provides the ability to snapshot and restore models or simulation engines.
+It's compatible with Python versions 3.10+.
+   
+For more information, see the documentation. : [pyjevsim](https://pyjevsim.readthedocs.io/en/latest/index.html)
+   
+## Installing
+You can install pyjevsim via
+```
+git clone https://github.com/eventsim/pyjevsim
+```
+   
+## Dependencies
+The only dependency required by pyjevsim is dill ~= 0.3.6 for model serialization and restoration.  
+dill is an essential library for serializing models and simulation states and can be installed via. 
+```
+pip install dill
+```
+   
+### Optional Dependencies
+pytest is an optional dependency required for running test cases and example executions. 
+You can install pyjevsim via
+```
+pip install pytest
+```
+   
+Additionally, you can install all necessary libraries, including optional dependencies, by running the following command:
+```
+pip install -r requirements.txt
+``` 
+
+## Working with pyjevsim
+Once you have installed the library, you can begin working with it.
+
+### Quick Start
+The docs describe how to configure a simulation via pyjevsim's BehaviorModel and SysExecutor.
+Check out the [documentation](link) to configure your simulation.
+
+### Example
+There is a banksim example that uses pyjevsim's DEVS functionality and journaling features.
+[documentation](link)
+
+## Execution Modes
+
+SysExecutor supports three execution modes via `ExecutionType`:
+
+| Mode | Description |
+|------|-------------|
+| `V_TIME` | Virtual time — simulation runs as fast as possible |
+| `R_TIME` | Real time — simulation paces itself to wall-clock time |
+| `HLA_TIME` | HLA/RTI-controlled time — time advancement is driven externally |
+
+```python
+from pyjevsim.system_executor import SysExecutor
+from pyjevsim.definition import ExecutionType
+
+se = SysExecutor(1, ex_mode=ExecutionType.V_TIME)
+```
+
+## Multi-threading Support
+
+SysExecutor provides thread-safe APIs for multi-threaded simulation environments where external threads inject events while the simulation runs.
+
+### Pause / Resume
+
+Pause the simulation to allow external threads to accumulate events, then resume.
+
+```python
+se.pause_sim()    # Pauses the simulation loop
+# External threads can safely call insert_external_event() while paused
+se.resume_sim()   # Resumes the simulation loop
+```
+
+### External Event Injection
+
+Insert events from external threads into the simulation. Thread-safe via internal synchronization.
+
+```python
+se.insert_external_event("port_name", message, scheduled_time=0)
+```
+
+### Output Event Callback
+
+Register a callback to be notified when output events are generated, avoiding polling.
+
+```python
+se.set_output_event_callback(lambda: print("output ready"))
+events = se.handle_external_output_event()
+```
+
+## HLA/RTI Integration (HLA_TIME Mode)
+
+For HLA/RTI-controlled simulations, use `HLA_TIME` mode with `step()` and `get_next_event_time()`.
+
+```python
+se = SysExecutor(1, ex_mode=ExecutionType.HLA_TIME)
+se.register_entity(model)
+se.init_sim()
+
+# RTI-driven loop
+while not se.is_terminated():
+    next_time = se.get_next_event_time()
+    # ... request time advance from RTI, wait for grant ...
+    granted_time = ...  # time granted by RTI
+    output_events = se.step(granted_time)
+    # ... publish output_events to RTI ...
+```
+
+### `step(granted_time)`
+Executes one simulation step up to the granted time. Returns output events generated during the step.
+
+### `get_next_event_time()`
+Returns the earliest scheduled event time (internal or external). Used to determine the Time Advance Request value for the RTI.
+
+## Graceful Termination
+
+```python
+se.terminate_simulation()  # Sets SIMULATION_TERMINATED state
+se.is_terminated()         # Returns True if terminated
+```
+
+Signal handlers (SIGTERM, SIGINT) automatically invoke `terminate_simulation()` on all registered SysExecutor instances.
+
+## License   
+Author: Changbeom Choi (@cbchoi)   
+Copyright (c) 2014-2020 Handong Global University      
+Copyright (c) 2021-2024 Hanbat National University    
+License: MIT.  The full license text is available at:   
+ - https://github.com/eventsim/pyjevsim/blob/main/LICENSE   

pyjevsim-1.0.0/README.md

@@ -0,0 +1,131 @@
+# pyjevsim
+## Introduction
+pyjevsim is a DEVS(discrete event system specification) environment that provides journaling functionality.
+It provides the ability to snapshot and restore models or simulation engines.
+It's compatible with Python versions 3.10+.
+   
+For more information, see the documentation. : [pyjevsim](https://pyjevsim.readthedocs.io/en/latest/index.html)
+   
+## Installing
+You can install pyjevsim via
+```
+git clone https://github.com/eventsim/pyjevsim
+```
+   
+## Dependencies
+The only dependency required by pyjevsim is dill ~= 0.3.6 for model serialization and restoration.  
+dill is an essential library for serializing models and simulation states and can be installed via. 
+```
+pip install dill
+```
+   
+### Optional Dependencies
+pytest is an optional dependency required for running test cases and example executions. 
+You can install pyjevsim via
+```
+pip install pytest
+```
+   
+Additionally, you can install all necessary libraries, including optional dependencies, by running the following command:
+```
+pip install -r requirements.txt
+``` 
+
+## Working with pyjevsim
+Once you have installed the library, you can begin working with it.
+
+### Quick Start
+The docs describe how to configure a simulation via pyjevsim's BehaviorModel and SysExecutor.
+Check out the [documentation](link) to configure your simulation.
+
+### Example
+There is a banksim example that uses pyjevsim's DEVS functionality and journaling features.
+[documentation](link)
+
+## Execution Modes
+
+SysExecutor supports three execution modes via `ExecutionType`:
+
+| Mode | Description |
+|------|-------------|
+| `V_TIME` | Virtual time — simulation runs as fast as possible |
+| `R_TIME` | Real time — simulation paces itself to wall-clock time |
+| `HLA_TIME` | HLA/RTI-controlled time — time advancement is driven externally |
+
+```python
+from pyjevsim.system_executor import SysExecutor
+from pyjevsim.definition import ExecutionType
+
+se = SysExecutor(1, ex_mode=ExecutionType.V_TIME)
+```
+
+## Multi-threading Support
+
+SysExecutor provides thread-safe APIs for multi-threaded simulation environments where external threads inject events while the simulation runs.
+
+### Pause / Resume
+
+Pause the simulation to allow external threads to accumulate events, then resume.
+
+```python
+se.pause_sim()    # Pauses the simulation loop
+# External threads can safely call insert_external_event() while paused
+se.resume_sim()   # Resumes the simulation loop
+```
+
+### External Event Injection
+
+Insert events from external threads into the simulation. Thread-safe via internal synchronization.
+
+```python
+se.insert_external_event("port_name", message, scheduled_time=0)
+```
+
+### Output Event Callback
+
+Register a callback to be notified when output events are generated, avoiding polling.
+
+```python
+se.set_output_event_callback(lambda: print("output ready"))
+events = se.handle_external_output_event()
+```
+
+## HLA/RTI Integration (HLA_TIME Mode)
+
+For HLA/RTI-controlled simulations, use `HLA_TIME` mode with `step()` and `get_next_event_time()`.
+
+```python
+se = SysExecutor(1, ex_mode=ExecutionType.HLA_TIME)
+se.register_entity(model)
+se.init_sim()
+
+# RTI-driven loop
+while not se.is_terminated():
+    next_time = se.get_next_event_time()
+    # ... request time advance from RTI, wait for grant ...
+    granted_time = ...  # time granted by RTI
+    output_events = se.step(granted_time)
+    # ... publish output_events to RTI ...
+```
+
+### `step(granted_time)`
+Executes one simulation step up to the granted time. Returns output events generated during the step.
+
+### `get_next_event_time()`
+Returns the earliest scheduled event time (internal or external). Used to determine the Time Advance Request value for the RTI.
+
+## Graceful Termination
+
+```python
+se.terminate_simulation()  # Sets SIMULATION_TERMINATED state
+se.is_terminated()         # Returns True if terminated
+```
+
+Signal handlers (SIGTERM, SIGINT) automatically invoke `terminate_simulation()` on all registered SysExecutor instances.
+
+## License   
+Author: Changbeom Choi (@cbchoi)   
+Copyright (c) 2014-2020 Handong Global University      
+Copyright (c) 2021-2024 Hanbat National University    
+License: MIT.  The full license text is available at:   
+ - https://github.com/eventsim/pyjevsim/blob/main/LICENSE   

pyjevsim-1.0.0/pyjevsim/__init__.py

@@ -0,0 +1,41 @@
+"""
+ Author: Changbeom Choi (@cbchoi)
+ Copyright (c) 2014-2020 Handong Global University
+ Copyright (c) 2014-2020 Hanbat National University
+ License: MIT.  The full license text is available at:
+  - https://github.com/eventsim/pyjevsim/blob/main/LICENSE
+"""
+__author__ = "me@cbchoi.info"
+__all__ = [
+    "behavior_model",
+    "behavior_executor",
+    "core_model",
+    "default_message_catcher",
+    "definition",
+    "executor_factory",
+    "executor",
+    "structural_model",
+    "structural_executor",
+    "executor_factory",
+    "system_executor",
+    "system_message",
+    "system_object",
+    "termination_manager",
+    "snapshot_manager"
+]
+
+from .definition import (
+    AttributeType,
+    Infinite,
+    ModelType,
+    ExecutionType,
+    SimulationMode,
+    SingletonType,
+)
+
+from .system_executor import SysExecutor
+from .system_message import SysMessage
+from .behavior_model import BehaviorModel
+from .structural_model import StructuralModel
+from .snapshot_manager import SnapshotManager
+from .restore_handler import RestoreHandler

pyjevsim-1.0.0/pyjevsim/atomic_model.py

@@ -0,0 +1,39 @@
+"""
+Author: Changbeom Choi (@cbchoi)
+Copyright (c) 2014-2020 Handong Global University
+Copyright (c) 2021-2024 Hanbat National University
+License: MIT.  The full license text is available at:
+https://github.com/eventsim/pyjevsim/blob/main/LICENSE
+
+This module contains a BehaivorModel object that allows you to implement the Discrete Event System Specification AtomicModel. 
+"""
+
+from abc import abstractmethod
+from collections import OrderedDict
+
+from .behavior_model import BehaviorModel
+from .definition import ModelType
+
+class AtomicModel(BehaviorModel):
+	def __init__(self, _name=""):
+		super().__init__(_name)
+
+	@abstractmethod
+	def ext_trans(self, port, msg):
+		"""Defines the external transition, to be implemented by subclasses"""
+		pass
+
+	@abstractmethod
+	def int_trans(self):
+		"""Defines the internal transition, to be implemented by subclasses"""
+		pass
+
+	@abstractmethod
+	def output(self, msg_deliver):
+		"""Defines the output function, to be implemented by subclasses"""
+		pass
+
+	@abstractmethod
+	def time_advance(self):
+		"""Defines the output function, to be implemented by subclasses"""
+		return -1

pyjevsim-1.0.0/pyjevsim/behavior_executor.py

@@ -0,0 +1,126 @@
+"""
+Author: Changbeom Choi (@cbchoi)
+Copyright (c) 2014-2020 Handong Global University
+Copyright (c) 2021-2024 Hanbat National University
+License: MIT.  The full license text is available at:
+https://github.com/eventsim/pyjevsim/blob/main/LICENSE
+
+This module contains a BehaviorExecutor, an object for executing a BehaviorModel.
+"""
+
+from .definition import Infinite
+from .executor import Executor
+
+class BehaviorExecutor(Executor):
+    """
+    A decorated form of the BehaviorModel, ready to be executed by the SysExecutor.
+    Manages the simulation time of the BehaviorModel and the information in the SysExecutor.
+
+    Args:
+        itime (int or Infinite): Time of instance creation
+        dtime (int or Infinite): Time of instance destruction
+        ename (str): SysExecutor name
+        behavior_model (ModelType.BEHAVIORAL): Behavior Model
+    """
+    def __init__(self, itime=Infinite, dtime=Infinite, ename="default", behavior_model=None, parent=None):
+        super().__init__(itime, dtime, ename, behavior_model, parent)
+
+        self._next_event_t = 0  # Next event time
+        self._cur_state = ""  # Current state of the behavior executor
+        self.request_time = float("inf")  # Request time initialized to infinity
+
+        self.behavior_model = behavior_model #Behavior Model
+        self._cancel_reschedule_f = False #cancel reschedule flag
+
+    def set_global_time(self, gtime):
+        """Sets the global time for the executor and behavior model"""
+        self.global_time = gtime
+        self.behavior_model.set_global_time(gtime)
+        
+    def get_core_model(self):
+        """Returns the core behavior model"""
+        return self.behavior_model
+
+    def __str__(self):
+        """Returns a string representation of the executor"""
+        return f"[N]:{self.get_name()}, [S]:{self._cur_state}"
+
+    def get_name(self):
+        """Returns the name of the behavior model"""
+        return self.behavior_model.get_name()
+
+    def get_engine_name(self):
+        """Returns the name of the engine"""
+        return self.engine_name
+
+    def set_engine_name(self, engine_name):
+        """Sets the name of the engine"""
+        self.engine_name = engine_name
+
+    def get_create_time(self):
+        """Returns the instance creation time"""
+        return self._instance_t
+
+    def get_destruct_time(self):
+        """Returns the destruction time"""
+        return self._destruct_t
+
+    def get_obj_id(self):
+        """Returns the object ID of the behavior model"""
+        return self.behavior_model.get_obj_id()
+
+    # State management
+    def get_cur_state(self):
+        """Returns the current state of the executor"""
+        return self._cur_state
+
+    def init_state(self, state):
+        """Initializes the state of the executor"""
+        self._cur_state = state
+
+    # External Transition
+    def ext_trans(self, port, msg):
+        """Handles external transition based on port and message"""
+        if self.behavior_model.get_cancel_flag():
+            self._cancel_reschedule_f = True
+
+        self.behavior_model.ext_trans(port, msg)
+
+    # Internal Transition
+    def int_trans(self):
+        """Handles internal transition"""
+        self.behavior_model.int_trans()
+
+    # Output Function
+    def output(self, msg_deliver):
+        """Executes the output function of the behavior model"""
+        return self.behavior_model.output(msg_deliver)
+
+    # Time Advance Function
+    def time_advance(self):
+        """Returns the time advance value for the current state"""
+        if self.behavior_model._cur_state in self.behavior_model._states:
+            return self.behavior_model._states[self.behavior_model._cur_state]
+
+        return -1
+
+    def set_req_time(self, global_time):
+        """Sets the request time based on the global time and time advance"""
+        self.set_global_time(global_time)
+        if self.time_advance() == Infinite:
+            self._next_event_t = Infinite
+            self.request_time = Infinite
+        else:
+            if self._cancel_reschedule_f:
+                self.request_time = min(self._next_event_t, global_time + self.time_advance())
+            else:
+                self.request_time = global_time + self.time_advance()
+
+    def get_req_time(self):
+        """Returns the request time and resets the cancel flag if necessary"""
+        if self._cancel_reschedule_f:
+            self._cancel_reschedule_f = False
+            self.behavior_model.reset_cancel_flag()
+        self._next_event_t = self.request_time
+        return self.request_time
+