# mitrasan22/chaotic-inventory-opt architecture

> Architecture diagram of the GitHub repository mitrasan22/chaotic-inventory-opt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mitrasan22/chaotic-inventory-opt
- Repository: https://github.com/mitrasan22/chaotic-inventory-opt

## Overview

FCIO is a Python library for non-stationary inventory control. The main workflow is to select a classical or FCIO policy, use it to determine orders as demand arrives, evolve inventory, and assess cost, service, and stability. FCIO adapts orders using demand-memory and chaos estimates; the library also documents multi-SKU control, analysis tools, robustness evaluation, and optional reinforcement-learning extensions. Some subsystem links below reflect README-level architecture because their implementation files were not excerpted.

Main entry points: [`src/chaotic_inventory_opt/core/inventory_system.py`](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/core/inventory_system.py) (Inventory system), [`src/chaotic_inventory_opt/control/fcio.py`](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/control/fcio.py) (FCIO policy), [`src/chaotic_inventory_opt/rl/env.py`](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/rl/env.py) (RL environment), [`src/chaotic_inventory_opt/chaos/lyapunov.py`](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/chaos/lyapunov.py) (Lyapunov estimator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Inventory control"]
  node_fcio["FCIO policy<br/>[fcio.py]"]
  node_classical["Classical policies<br/>[classical.py]"]
  node_network["Multi-SKU control<br/>[network.py]"]
end

subgraph group_dynamics["Inventory dynamics"]
  node_system["Inventory system"]
  node_dynamics["Inventory dynamics<br/>[dynamics.py]"]
  node_cost["Cost model<br/>[cost.py]"]
end

subgraph group_analysis["Demand analysis"]
  node_hurst["Hurst estimator<br/>[hurst.py]"]
  node_rs["Rescaled range<br/>[rs_analysis.py]"]
  node_wavelets["Wavelet analysis<br/>[wavelets.py]"]
  node_lyapunov["Lyapunov estimator<br/>[lyapunov.py]"]
  node_entropy["Sample entropy<br/>[entropy.py]"]
  node_recurrence["Recurrence analysis<br/>[recurrence.py]"]
  node_regime["Regime classifier<br/>[classifier.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_performance["Performance metrics<br/>[performance.py]"]
  node_stability["Stability metrics<br/>[stability.py]"]
  node_robustness["Robustness analysis<br/>[robustness.py]"]
  node_validation["Input validation<br/>[validation.py]"]
end

subgraph group_extensions["Optional extensions"]
  node_rl_env["RL environment<br/>[env.py]"]
  node_rl_reward["RL rewards<br/>[reward.py]"]
  node_rl_agent["RL agent<br/>[agent.py]"]
end

node_user(("Library user"))

node_user -->|"selects policy"| node_fcio
node_user -->|"selects policy"| node_classical
node_fcio -->|"estimates memory"| node_hurst
node_fcio -->|"estimates chaos"| node_lyapunov
node_fcio -.->|"sets orders"| node_system
node_classical -.->|"sets orders"| node_system
node_network -->|"orchestrates"| node_fcio
node_system -.->|"provides inventory"| node_cost
node_system -.->|"provides trajectory"| node_performance
node_system -.->|"provides trajectory"| node_stability
node_stability -->|"estimates exponent"| node_lyapunov
node_rl_env -->|"advances state"| node_system
node_rl_env -->|"computes cost"| node_cost
node_rl_agent -.->|"acts in"| node_rl_env
node_rl_reward -.->|"uses stability signal"| node_lyapunov

click node_fcio "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/control/fcio.py"
click node_classical "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/control/classical.py"
click node_network "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/control/network.py"
click node_system "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/core/inventory_system.py"
click node_dynamics "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/core/dynamics.py"
click node_cost "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/core/cost.py"
click node_hurst "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/fractal/hurst.py"
click node_rs "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/fractal/rs_analysis.py"
click node_wavelets "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/fractal/wavelets.py"
click node_lyapunov "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/chaos/lyapunov.py"
click node_entropy "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/chaos/entropy.py"
click node_recurrence "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/chaos/recurrence.py"
click node_regime "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/regimes/classifier.py"
click node_performance "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/evaluation/performance.py"
click node_stability "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/evaluation/stability.py"
click node_robustness "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/evaluation/robustness.py"
click node_validation "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/utils/validation.py"
click node_rl_env "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/rl/env.py"
click node_rl_reward "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/rl/reward.py"
click node_rl_agent "https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/rl/agent.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fcio,node_classical,node_network,node_user toneBlue
class node_system,node_dynamics,node_cost toneAmber
class node_hurst,node_rs,node_wavelets,node_lyapunov,node_entropy,node_recurrence,node_regime toneMint
class node_performance,node_stability,node_robustness,node_validation toneRose
class node_rl_env,node_rl_reward,node_rl_agent toneIndigo
```

## Components

### Inventory control

- [FCIO policy](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/control/fcio.py): `src/chaotic_inventory_opt/control/fcio.py`
- [Classical policies](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/control/classical.py): `src/chaotic_inventory_opt/control/classical.py`
- [Multi-SKU control](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/control/network.py): `src/chaotic_inventory_opt/control/network.py`

### Inventory dynamics

- [Inventory system](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/core/inventory_system.py): `src/chaotic_inventory_opt/core/inventory_system.py`
- [Inventory dynamics](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/core/dynamics.py): `src/chaotic_inventory_opt/core/dynamics.py`
- [Cost model](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/core/cost.py): `src/chaotic_inventory_opt/core/cost.py`

### Demand analysis

- [Hurst estimator](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/fractal/hurst.py): `src/chaotic_inventory_opt/fractal/hurst.py`
- [Rescaled range](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/fractal/rs_analysis.py): `src/chaotic_inventory_opt/fractal/rs_analysis.py`
- [Wavelet analysis](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/fractal/wavelets.py): `src/chaotic_inventory_opt/fractal/wavelets.py`
- [Lyapunov estimator](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/chaos/lyapunov.py): `src/chaotic_inventory_opt/chaos/lyapunov.py`
- [Sample entropy](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/chaos/entropy.py): `src/chaotic_inventory_opt/chaos/entropy.py`
- [Recurrence analysis](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/chaos/recurrence.py): `src/chaotic_inventory_opt/chaos/recurrence.py`
- [Regime classifier](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/regimes/classifier.py): `src/chaotic_inventory_opt/regimes/classifier.py`

### Evaluation

- [Performance metrics](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/evaluation/performance.py): `src/chaotic_inventory_opt/evaluation/performance.py`
- [Stability metrics](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/evaluation/stability.py): `src/chaotic_inventory_opt/evaluation/stability.py`
- [Robustness analysis](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/evaluation/robustness.py): `src/chaotic_inventory_opt/evaluation/robustness.py`
- [Input validation](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/utils/validation.py): `src/chaotic_inventory_opt/utils/validation.py`

### Optional extensions

- [RL environment](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/rl/env.py): `src/chaotic_inventory_opt/rl/env.py`
- [RL rewards](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/rl/reward.py): `src/chaotic_inventory_opt/rl/reward.py`
- [RL agent](https://github.com/mitrasan22/chaotic-inventory-opt/blob/master/src/chaotic_inventory_opt/rl/agent.py): `src/chaotic_inventory_opt/rl/agent.py`

### Other components

- **Library user**

## Connections

- Library user → FCIO policy: selects policy (evidence: `README.md`)
- Library user → Classical policies: selects policy (evidence: `README.md`)
- FCIO policy → Hurst estimator: estimates memory (evidence: `src/chaotic_inventory_opt/control/fcio.py`)
- FCIO policy → Lyapunov estimator: estimates chaos (evidence: `src/chaotic_inventory_opt/control/fcio.py`)
- FCIO policy → Inventory system: sets orders
- Classical policies → Inventory system: sets orders
- Multi-SKU control → FCIO policy: orchestrates (evidence: `src/chaotic_inventory_opt/control/network.py`)
- Inventory system → Cost model: provides inventory
- Inventory system → Performance metrics: provides trajectory
- Inventory system → Stability metrics: provides trajectory
- Stability metrics → Lyapunov estimator: estimates exponent (evidence: `src/chaotic_inventory_opt/evaluation/stability.py`)
- RL environment → Inventory system: advances state (evidence: `src/chaotic_inventory_opt/rl/env.py`)
- RL environment → Cost model: computes cost (evidence: `src/chaotic_inventory_opt/rl/env.py`)
- RL agent → RL environment: acts in
- RL rewards → Lyapunov estimator: uses stability signal (evidence: `src/chaotic_inventory_opt/rl/reward.py`)