Metadata-Version: 2.5
Name: food-distribution-gym
Version: 0.1.0a1
Summary: Gymnasium environment for reinforcement learning in food distribution and security logistics.
Project-URL: Homepage, https://github.com/ui-iros/food-distribution-gym
Project-URL: Repository, https://github.com/ui-iros/food-distribution-gym
Project-URL: Issues, https://github.com/ui-iros/food-distribution-gym/issues
Project-URL: Documentation, https://github.com/ui-iros/food-distribution-gym#readme
Author: Food Distribution Gym contributors
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: gymnasium<1.3.0,>=1.2.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Provides-Extra: render
Requires-Dist: pygame-ce>=2.5; extra == 'render'
Provides-Extra: research
Requires-Dist: matplotlib>=3.7; extra == 'research'
Requires-Dist: pandas>=1.5; extra == 'research'
Requires-Dist: pygame-ce>=2.5; extra == 'research'
Requires-Dist: stable-baselines3<3,>=2.7; extra == 'research'
Requires-Dist: torch>=2.3; extra == 'research'
Description-Content-Type: text/markdown

# Food Distribution Gym

A reinforcement-learning environment built on The Farama Foundation's
[Gymnasium](https://github.com/Farama-Foundation/Gymnasium) for food-distribution
and food-security logistics research.

The environment models trade between cities with multiple commodities, demand
and supply dynamics, price fluctuations, cash constraints, and climate and pest
shocks. Agents distribute food across the network to reduce shortages.

Maintained under [IROS Lab](https://github.com/ui-iros), Faculty of Computer
Science (Fasilkom), Universitas Indonesia. The project is in alpha development.

## Installation

From a source checkout:

```bash
git clone https://github.com/ui-iros/food-distribution-gym.git
cd food-distribution-gym
python -m pip install -e .
```

The distribution is named `food-distribution-gym`; import it as
`food_distribution_gym`. The first alpha version is `0.1.0a1`. Once that release
is published on PyPI, installation without a clone will be:

```bash
python -m pip install --pre food-distribution-gym
```

Optional dependencies for the viewer and research scripts:

```bash
python -m pip install -e ".[render]"
python -m pip install -e ".[research]"
```

The base package requires Gymnasium, NumPy, and PyYAML. The `render` extra adds
Pygame; `research` also includes Stable-Baselines3, PyTorch, pandas, and Matplotlib.

### Isolated Environment

Use a virtual environment. On Windows PowerShell:

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[research]"
.\.venv\Scripts\python.exe -m pip check
```

On Linux/macOS:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[research]"
python -m pip check
```

Use the same interpreter for installation and execution.

## Repository Structure

```text
food-distribution-gym/
|-- food_distribution_gym/       # Installable environment package
|   |-- __init__.py             # Gymnasium registration and public imports
|   |-- __main__.py             # Viewer entry point
|   |-- envs/
|   |   `-- food_security_env.py
|   |-- utils/                  # Configuration loading helpers
|   |-- config/                 # Bundled YAML scenarios
|   |-- assets/                 # Commodity, climate, and pest icons
|   `-- viewer.py               # Interactive simulation and replay
|-- scripts/                    # Training, evaluation, plotting, recording
|-- data/                       # CSV inputs for scenario generation
|-- tests/                      # Environment and installed-package checks
|-- docs/                       # Experiments and release instructions
|-- .github/workflows/          # CI and PyPI Trusted Publishing
|-- LICENSE
|-- CHANGELOG.md
|-- README.md
|-- pyproject.toml
`-- requirements.txt            # Install the research dependencies
```

Only `food_distribution_gym/`, including its scenarios and icons, is installed
in the wheel. Research scripts, example CSVs, and documentation are included in
the source distribution. Checkpoints and generated results are not bundled.

## Experiments

Install `.[research]`, then run scripts from the repository root:

```bash
python scripts/PPO.py --seed 42 --total-timesteps 1000000
python scripts/A2C.py --seed 42 --total-timesteps 1000000
python scripts/SAC.py --seed 42 --total-timesteps 1000000
python scripts/TD3.py --seed 42 --total-timesteps 1000000
python scripts/evaluate_and_plot.py --experiments 30
python scripts/plot_training_curves.py --algo ppo
python scripts/plot_comparison.py
```

All four training scripts use the bundled Indonesian six-city, two-commodity
scenario by default. Models are saved under `models/`, CSVs and plots under
`outputs/`, and episode recordings under `episode_logs/`. Generated outputs are
ignored by Git. Training uses eight parallel environments with the `spawn`
start method and a guarded entry point for Windows and Linux compatibility.

See [scripts/README.md](https://github.com/ui-iros/food-distribution-gym/blob/main/scripts/README.md)
and [docs/experiments.md](https://github.com/ui-iros/food-distribution-gym/blob/main/docs/experiments.md).

## Usage

| Property | Value |
| --- | --- |
| Action Space | `Box(-1.0, 1.0, (M * C * (C - 1) // 2,), float32)` |
| Observation Space | `Box(0.0, 1.0, (obs_dim,), float32)` |
| Create | `gymnasium.make("FoodDistribution-v0")` |
| Default Scenario | Six Indonesian provinces, two commodities (rice and corn) |
| Default Episode Length | 100 steps |

Import `food_distribution_gym` before creating the environment to register its ID:

```python
import gymnasium as gym
import food_distribution_gym

food_distribution_gym.register_envs()
env = gym.make("FoodDistribution-v0")

obs, info = env.reset(seed=42)
env.action_space.seed(42)
terminated = truncated = False
while not (terminated or truncated):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
env.close()
```

Here, `C` is the number of cities and `M` the number of commodities. The default
scenario has 30 action components and 108 observation components. Each action
specifies the signed trade quantity for one commodity and pair of cities.
Positive values ship from the first city to the second; negative values reverse
the direction. Quantities are scaled by `X_max` and projected into feasible
integer flows using supply and, when enabled, cash constraints.

Observations contain normalized cash, stock, demand, and prices, plus one-step
climate and pest transition probabilities when enabled. The reward combines
shortage, cash-risk, and logistics-cost penalties. Their default weights are
`1.0`, `0.0`, and `0.0`, respectively.

### Interactive Viewer

Install `.[render]` from source, then launch:

```bash
python -m food_distribution_gym
```

The equivalent command `food-distribution-viewer` launches the same viewer.
The viewer discovers bundled scenarios independently of the current working
directory. Models and replay files are read from `models/` and `episode_logs/`
under the current working directory. Loading trained models requires the
`research` extra. With no model loaded, the live simulation uses random actions.

The viewer displays the city network, commodity flows, stock and demand, cash,
and climate and pest states. It supports dragging cities, zoom and pan,
commodity selection, and manual trade control.

| Key | Action |
| --- | --- |
| `Space` | Pause or play |
| Right / left arrow | Step forward / backward (backward in Replay mode) |
| `1`-`9` | Select commodity |
| `R` | Reset episode |
| `M` | Toggle manual control in Live mode |
| `+` / `-` | Adjust playback speed |
| `H` | Toggle help |
| `F11` | Toggle fullscreen |
| `Esc` | Quit |

The interactive viewer is separate from `env.render()`, which prints simulator
state. An RGB renderer and Gymnasium `RecordVideo` integration are not included.

### Scenario Configuration

The default scenario models Jawa Timur, Sulawesi Selatan, Sumatera Selatan,
DKI Jakarta, Maluku, and Kalimantan Timur. Bundled YAML scenarios:

| Filename | Scenario |
| --- | --- |
| `config_indonesia_6city_2comm.yaml` | Default scenario from Indonesian province data |
| `config_6city_2comm_climate_pest.yaml` | Six cities, two commodities, climate and pest shocks |
| `config_6city_2comm_climate_pest_harsh.yaml` | Six-city scenario with harsher shocks |
| `config_10city_4comm_climate_pest.yaml` | Ten cities and four commodities |

Load a bundled scenario by filename or a custom scenario by file path:

```python
import gymnasium as gym
import food_distribution_gym

config = food_distribution_gym.load_config("config_6city_2comm_climate_pest.yaml")
env = gym.make("FoodDistribution-v0", config=config)
obs, info = env.reset(seed=42)
env.close()
```

`FoodSecurityEnv(config)` remains available directly from
`food_distribution_gym`. YAML settings control initial stocks, demand, prices,
cash, trade limits, climate and pest transitions, rewards, and the horizon.
Changing city or commodity counts changes the policy dimensions; use a
checkpoint trained for the selected configuration.

## Episode Recording

Training records episodes through `EpisodeLoggerCallback`. For a separate
rollout from a saved PPO model:

```bash
python scripts/episode_logger.py --model models/ppo_indonesia_6city_2comm_seed42.zip --config config_indonesia_6city_2comm.yaml --output episode_logs/ppo_seed42.pkl --seed 42
```

Open the saved episode in the viewer's Replay mode to inspect states, actions,
trade flows, and reward components.

## License and Releases

The code is licensed under the
[MIT License](https://github.com/ui-iros/food-distribution-gym/blob/main/LICENSE).
See the [release guide](https://github.com/ui-iros/food-distribution-gym/blob/main/docs/releasing.md)
for local checks, TestPyPI, Trusted Publishing, and the first alpha release.

Package versions such as `0.1.0a1` are separate from the environment ID
`FoodDistribution-v0`. Record both the package version and commit in experiments.

## Acknowledgements

The food-security code was originally developed in
[tttor/discounting-free](https://github.com/tttor/discounting-free). This
repository retains the relevant history. Package organization and documentation
follow [Cleaning Robots Gym](https://github.com/ui-iros/cleaning-robots-gym).
