scar_sim

SCAR SIM

Supply Chain Adaptation and Resilience Simulator

Setup

Make sure you have Python 3.11.x (or higher) installed on your system. You can download it here.

Installation

pip install scar_sim

Getting Started

Docs
Git

Basic Example

from scar_sim.entity import Arc, Node
from scar_sim.order import Order
from scar_sim.simulation import Simulation


simulation = Simulation()

# Create nodes
supplier_0 = simulation.add_object(
    Node(
        processing_min_time=0.8,
        processing_avg_time=1.0,
        processing_sd_time=0.02,
        processing_cashflow_per_unit=-50,
        metadata={
            "loc": "cn_ningbo",
            "otype": "node_supplier",
        },
    )
)
factory_1 = simulation.add_object(
    Node(
        processing_min_time=0.2,
        processing_avg_time=0.4,
        processing_sd_time=0.1,
        processing_cashflow_per_unit=-15,
        metadata={
            "loc": "us_ks_kc",
            "otype": "node_factory",
        },
    )
)

# Create arcs between nodes
arc_0_1 = simulation.add_object(
    Arc(
        origin_node=supplier_0,
        destination_node=factory_1,
        processing_min_time=2.0,
        processing_avg_time=2.0,
        processing_sd_time=0.05,
        processing_cashflow_per_unit=-10,
        metadata={
            "loc": "oc_pa",
            "otype": "arc_ocean",
        },
    )
)

order = simulation.add_object(
    Order(
        origin_node=supplier_0,
        destination_node=factory_1,
        units=1,
        planned_path=simulation.graph.get_optimal_path(
            supplier_0, factory_1, "cashflow"
        ),
    )
)

simulation.add_event(
    time_delta=0.0,
    func=order.start,
)

simulation.run(max_time=10.0)

print(simulation.orders[0].history[-1]) #=>
# {
#     'time': 2.9971,
#     'time_delta': 0.0,
#     'order_id': 3,
#     'current_obj_id': 1,
#     'meta': {
#         'loc': 'us_ks_kc',
#         'otype': 'node_factory',
#         'time': 2
#     },
#     'status': 'completed',
#     'cashflow': 0.0
# }

Development

To avoid extra development overhead, we expect all developers to use a unix based environment (Linux or Mac). If you use Windows, please use WSL2.

For development, we test using Docker so we can lock system deps and swap out python versions easily. However, you can also use a virtual environment if you prefer. We provide a test script and a prettify script to help with development.

Making Changes

1) Fork the repo and clone it locally. 2) Make your modifications. 3) Use Docker or a virtual environment to run tests and make sure they pass. 4) Prettify your code. 5) DO NOT GENERATE DOCS. - We will generate the docs and update the version number when we are ready to release a new version. 6) Only commit relevant changes and add clear commit messages. - Atomic commits are preferred. 7) Submit a pull request.

Docker

Make sure Docker is installed and running.

Create a docker container and drop into a shell
- ./run.sh
Run all tests (see ./utils/test.sh)
- ./run.sh test
Prettify the code (see ./utils/prettify.sh)
- ./run.sh prettify
Note: You can and should modify the Dockerfile to test different python versions.

Virtual Environment

Create a virtual environment
- python3.XX -m venv venv
  - Replace 3.XX with your python version (3.11 or higher)
Activate the virtual environment
- source venv/bin/activate
Install the development requirements
- pip install -r requirements/dev.txt
Run Tests
- ./utils/test.sh
Prettify Code
- ./utils/prettify.sh

View Source

  1"""
  2# SCAR SIM
  3[![PyPI version](https://badge.fury.io/py/scar_sim.svg)](https://badge.fury.io/py/scar_sim)
  4[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5
  6Supply Chain Adaptation and Resilience Simulator
  7
  8# Setup
  9
 10Make sure you have Python 3.11.x (or higher) installed on your system. You can download it [here](https://www.python.org/downloads/).
 11
 12## Installation
 13
 14```
 15pip install scar_sim
 16```
 17
 18## Getting Started
 19
 20- [Docs](https://connor-makowski.github.io/scar_sim/scar_sim.html)
 21- [Git](https://github.com/connor-makowski/scar_sim)
 22
 23### Basic Example
 24
 25```py
 26from scar_sim.entity import Arc, Node
 27from scar_sim.order import Order
 28from scar_sim.simulation import Simulation
 29
 30
 31simulation = Simulation()
 32
 33# Create nodes
 34supplier_0 = simulation.add_object(
 35    Node(
 36        processing_min_time=0.8,
 37        processing_avg_time=1.0,
 38        processing_sd_time=0.02,
 39        processing_cashflow_per_unit=-50,
 40        metadata={
 41            "loc": "cn_ningbo",
 42            "otype": "node_supplier",
 43        },
 44    )
 45)
 46factory_1 = simulation.add_object(
 47    Node(
 48        processing_min_time=0.2,
 49        processing_avg_time=0.4,
 50        processing_sd_time=0.1,
 51        processing_cashflow_per_unit=-15,
 52        metadata={
 53            "loc": "us_ks_kc",
 54            "otype": "node_factory",
 55        },
 56    )
 57)
 58
 59# Create arcs between nodes
 60arc_0_1 = simulation.add_object(
 61    Arc(
 62        origin_node=supplier_0,
 63        destination_node=factory_1,
 64        processing_min_time=2.0,
 65        processing_avg_time=2.0,
 66        processing_sd_time=0.05,
 67        processing_cashflow_per_unit=-10,
 68        metadata={
 69            "loc": "oc_pa",
 70            "otype": "arc_ocean",
 71        },
 72    )
 73)
 74
 75order = simulation.add_object(
 76    Order(
 77        origin_node=supplier_0,
 78        destination_node=factory_1,
 79        units=1,
 80        planned_path=simulation.graph.get_optimal_path(
 81            supplier_0, factory_1, "cashflow"
 82        ),
 83    )
 84)
 85
 86simulation.add_event(
 87    time_delta=0.0,
 88    func=order.start,
 89)
 90
 91simulation.run(max_time=10.0)
 92
 93print(simulation.orders[0].history[-1]) #=>
 94# {
 95#     'time': 2.9971,
 96#     'time_delta': 0.0,
 97#     'order_id': 3,
 98#     'current_obj_id': 1,
 99#     'meta': {
100#         'loc': 'us_ks_kc',
101#         'otype': 'node_factory',
102#         'time': 2
103#     },
104#     'status': 'completed',
105#     'cashflow': 0.0
106# }
107
108```
109
110## Development
111
112To avoid extra development overhead, we expect all developers to use a unix based environment (Linux or Mac). If you use Windows, please use WSL2.
113
114For development, we test using Docker so we can lock system deps and swap out python versions easily. However, you can also use a virtual environment if you prefer. We provide a test script and a prettify script to help with development.
115
116## Making Changes
117
1181) Fork the repo and clone it locally.
1192) Make your modifications.
1203) Use Docker or a virtual environment to run tests and make sure they pass.
1214) Prettify your code.
1225) **DO NOT GENERATE DOCS**.
123    - We will generate the docs and update the version number when we are ready to release a new version.
1246) Only commit relevant changes and add clear commit messages.
125    - Atomic commits are preferred.
1267) Submit a pull request.
127
128## Docker
129
130Make sure Docker is installed and running.
131
132- Create a docker container and drop into a shell
133    - `./run.sh`
134- Run all tests (see ./utils/test.sh)
135    - `./run.sh test`
136- Prettify the code (see ./utils/prettify.sh)
137    - `./run.sh prettify`
138
139- Note: You can and should modify the `Dockerfile` to test different python versions.
140
141## Virtual Environment
142
143- Create a virtual environment
144    - `python3.XX -m venv venv`
145        - Replace `3.XX` with your python version (3.11 or higher)
146- Activate the virtual environment
147    - `source venv/bin/activate`
148- Install the development requirements
149    - `pip install -r requirements/dev.txt`
150- Run Tests
151    - `./utils/test.sh`
152- Prettify Code
153    - `./utils/prettify.sh`"""