stokasta 0.0.1__tar.gz

stokasta-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2025-2026 Ziang Liu
+
+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.

stokasta-0.0.1/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: stokasta
+Version: 0.0.1
+Summary: Inventory-control problems as Gymnasium environments (0.0.1: one environment; first full release in preparation)
+Project-URL: Homepage, https://github.com/stokasta
+Author: Ziang Liu
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Requires-Dist: gymnasium>=1.0
+Requires-Dist: numpy>=2.0
+Description-Content-Type: text/markdown
+
+# Stokasta
+
+*Stokasta* (sto-KAS-ta) is Esperanto for *stochastic*.
+
+Stokasta is a benchmark of inventory-control problems as Gymnasium
+environments. Version 0.0.1 ships one of them: the single-item dynamic
+inventory model with a fixed ordering cost and backorders, whose optimal
+policy is (s, S) (Scarf 1960; Snyder and Shen 2019, Example 4.7).
+
+```python
+import gymnasium as gym
+import stokasta  # registers the environments
+
+env = gym.make("stokasta/DynamicInventory-v0")
+obs, info = env.reset(seed=0)
+obs, reward, terminated, truncated, info = env.step(10)  # order 10 units
+```
+
+The reward is the negative of the period's holding, backorder and fixed
+ordering cost. The first full release, in preparation at
+https://github.com/stokasta, adds the other models, their exact Markov
+decision process export, and a problem set with reference costs.

stokasta-0.0.1/README.md

@@ -0,0 +1,22 @@
+# Stokasta
+
+*Stokasta* (sto-KAS-ta) is Esperanto for *stochastic*.
+
+Stokasta is a benchmark of inventory-control problems as Gymnasium
+environments. Version 0.0.1 ships one of them: the single-item dynamic
+inventory model with a fixed ordering cost and backorders, whose optimal
+policy is (s, S) (Scarf 1960; Snyder and Shen 2019, Example 4.7).
+
+```python
+import gymnasium as gym
+import stokasta  # registers the environments
+
+env = gym.make("stokasta/DynamicInventory-v0")
+obs, info = env.reset(seed=0)
+obs, reward, terminated, truncated, info = env.step(10)  # order 10 units
+```
+
+The reward is the negative of the period's holding, backorder and fixed
+ordering cost. The first full release, in preparation at
+https://github.com/stokasta, adds the other models, their exact Markov
+decision process export, and a problem set with reference costs.

stokasta-0.0.1/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stokasta"
+version = "0.0.1"
+description = "Inventory-control problems as Gymnasium environments (0.0.1: one environment; first full release in preparation)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Ziang Liu" }]
+dependencies = ["numpy>=2.0", "gymnasium>=1.0"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://github.com/stokasta"

stokasta-0.0.1/src/stokasta/__init__.py

@@ -0,0 +1,17 @@
+"""Stokasta: inventory-control problems as Gymnasium environments.
+
+Version 0.0.1 ships one environment, registered as
+``stokasta/DynamicInventory-v0`` (``stokasta.envs.dynamic_inventory:
+DynamicInventoryEnv``). The first full release adds the other models, their
+exact Markov decision process export, and a problem set with reference costs.
+"""
+
+from gymnasium.envs.registration import register
+
+__version__ = "0.0.1"
+
+register(
+    id="stokasta/DynamicInventory-v0",
+    entry_point="stokasta.envs.dynamic_inventory:DynamicInventoryEnv",
+    max_episode_steps=1000,
+)

stokasta-0.0.1/src/stokasta/envs/__init__.py

@@ -0,0 +1,3 @@
+from stokasta.envs.dynamic_inventory import DynamicInventoryEnv
+
+__all__ = ["DynamicInventoryEnv"]

stokasta-0.0.1/src/stokasta/envs/dynamic_inventory.py

@@ -0,0 +1,164 @@
+"""Dynamic inventory: one item, a fixed cost per order, zero lead time, backorders.
+
+The textbook model whose optimal policy is ``(s, S)`` (Scarf 1960), in the
+form of Snyder and Shen's (2019) Example 4.7. The state is the inventory
+level, negative for a backlog; an order arrives before the period's demand,
+and holding and backorder costs are charged on the level after it. The reward
+is the negative of the period's cost.
+
+References
+----------
+L. V. Snyder and Z. J. M. Shen, Fundamentals of Supply Chain Theory. Wiley,
+2019, Example 4.7, p. 121.
+
+H. Scarf, "The optimality of (s, S) policies in the dynamic inventory
+problem," Mathematical Methods in the Social Sciences, pp. 196-202, 1960.
+"""
+
+from typing import Any
+
+import gymnasium as gym
+import numpy as np
+from gymnasium import spaces
+
+
+class DynamicInventoryEnv(gym.Env):
+    """
+    Parameters
+    ----------
+    holding_cost: float, default=1
+        Cost per unit on hand at the end of a period.
+
+    shortage_cost: float, default=4
+        Cost per unit of backlog at the end of a period, charged every period
+        the unit stays owed -- a unit short for ``k`` periods costs ``k`` times
+        this, not once per unit of unmet demand.
+
+    ordering_cost: float, default=5
+        Fixed cost of an order, charged whenever the order quantity is
+        positive, whatever its size. There is no per-unit cost.
+
+    demand: dict, optional
+        Per-period demand, as ``{"type": "poisson", "mean": m}``. Defaults to
+        Poisson with mean 6. Version 0.0.1 supports Poisson demand only.
+
+    min_state: int, default=-20
+        Floor of the inventory level: the next level is clipped up to it, which
+        forgives the backlog below it. At most 0 (see ``max_state``).
+
+    max_state: int, default=20
+        Ceiling of the inventory level: the next level is clipped down to it,
+        which disposes of the stock above it for free. At least 0: the box
+        ``[min_state, max_state]`` has to hold the level 0 the default
+        :meth:`reset` starts from, and a box without it raises ``ValueError``.
+
+    max_action: int, default=30
+        Largest order per period; sets the action space
+        ``{0, ..., max_action}``, and :meth:`step` clips any larger order.
+
+    random_init: bool, default=False
+        Whether :meth:`reset` draws the initial level uniformly from the box
+        instead of starting at 0. For training; ``options={"random": ...}``
+        overrides it for one reset.
+    """
+
+    metadata = {"render_modes": []}
+
+    def __init__(
+        self,
+        render_mode=None,
+        holding_cost=1,
+        shortage_cost=4,
+        ordering_cost=5,
+        demand=None,
+        min_state=-20,
+        max_state=20,
+        max_action=30,
+        random_init=False,
+    ):
+        self.render_mode = render_mode
+        self.random_init = bool(random_init)
+
+        self.holding_cost = holding_cost
+        self.shortage_cost = shortage_cost
+        self.ordering_cost = ordering_cost
+
+        spec = {"type": "poisson", "mean": 6} if demand is None else dict(demand)
+        if spec.get("type") != "poisson" or set(spec) != {"type", "mean"}:
+            raise ValueError(
+                f"demand must be {{'type': 'poisson', 'mean': m}} in version "
+                f"0.0.1, got {demand!r}"
+            )
+        if not spec["mean"] > 0:
+            raise ValueError(f"the Poisson mean must be positive, got {spec['mean']}")
+        self.demand_mean = float(spec["mean"])
+
+        if not min_state <= 0 <= max_state:
+            raise ValueError(
+                f"the box [min_state, max_state] = [{min_state}, {max_state}] "
+                f"must contain 0, the level reset() starts from"
+            )
+
+        self.min_state = min_state
+        self.max_state = max_state
+        self.max_action = max_action
+
+        self.observation_space = spaces.Box(
+            low=np.array([self.min_state], dtype=np.int64),
+            high=np.array([self.max_state], dtype=np.int64),
+            shape=(1,),
+            dtype=np.int64,
+        )
+        self.action_space = spaces.Discrete(self.max_action + 1)
+
+    def reset(self, *, seed: int | None = None, options: dict[str, Any] | None = None):
+        super().reset(seed=seed)
+
+        use_random = (
+            self.random_init
+            if options is None
+            else bool(options.get("random", self.random_init))
+        )
+
+        if use_random:
+            observation = self.np_random.integers(
+                self.min_state, self.max_state + 1, size=(1,), dtype=np.int64
+            )
+        else:
+            observation = np.zeros((1,), dtype=np.int64)
+
+        self.observation = observation
+        return observation, {}
+
+    def step(self, action):
+        demand = int(self.np_random.poisson(self.demand_mean))
+        action_value = min(max(int(np.asarray(action).item()), 0), self.max_action)
+
+        state = np.copy(self.observation)
+        next_state, reward = self._transition_reward(state, action_value, demand)
+
+        self.observation = next_state
+
+        info = {
+            "state": state,
+            "demand": demand,
+            "action": action_value,
+            "reward": reward,
+        }
+        return next_state, reward, False, False, info
+
+    def _transition_reward(self, state, action, demand):
+        level = int(state[0]) + action - demand
+        on_hand = max(0, level)
+        shortage = max(0, -level)
+
+        next_state = np.array(
+            [min(max(level, self.min_state), self.max_state)], dtype=np.int64
+        )
+
+        reward = -(
+            self.holding_cost * on_hand
+            + self.shortage_cost * shortage
+            + self.ordering_cost * (action > 0)
+        )
+        return next_state, float(reward)