EnergyQuantResearch · EnergyQuantResearch · Mar 27, 2026 · Mar 26, 2026 · Mar 26, 2026 · Mar 27, 2026
diff --git a/.github/workflows/light-ci.yml b/.github/workflows/light-ci.yml
@@ -16,12 +16,18 @@ jobs:
       - name: Set up Python 3.8
         uses: actions/setup-python@v5
         with:
-          python-version: '3.8'
+          python-version: '3.11'
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade "pip<24.1" "setuptools<66" "wheel<0.38"
-          python -m pip install --no-build-isolation -r requirements-ci.txt
+          python -m pip install --upgrade pip
+          python -m pip install -c requirements-ci.txt -e .[dev]
+
+      - name: Ruff lint
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
 
       - name: Run lightweight test suite
         run: pytest -q -m "not powerflow"
diff --git a/MANIFEST.in b/MANIFEST.in
diff --git a/README.md b/README.md
@@ -8,25 +8,25 @@ RL-ADN now supports `topology-as-scenario` for the `34-bus` and `69-bus` feeders
 
 ## Quickstart
 
-Install runtime dependencies:
+Install the package:
 
 ```bash
-py -3 -m pip install -r requirements.txt
+py -3 -m pip install .
 ```
 
 Install the development toolchain:
 
 ```bash
-py -3 -m pip install -r requirements-dev.txt
+py -3 -m pip install -e .[dev]
 ```
 
-Run the lightweight test suite:
+Run the lightweight verification suite:
 
 ```bash
-py -3 -m pytest tests -q -m "not powerflow"
+py -3 -m pytest -q -m "not powerflow"
 ```
 
-Some power-flow validation tests require `pandapower`. If it is not installed, those tests are skipped automatically.
+Power-flow validation tests require the optional `pandapower` extra and are skipped when it is not installed.
 
 ## First Import
 
@@ -35,7 +35,7 @@ from rl_adn import PowerNetEnv, make_env_config
 
 config = make_env_config()
 env = PowerNetEnv(config)
-state, info = env.reset(return_info=True)
+state, info = env.reset(seed=2026)
 ```
 
 Run the script-style quickstart:
@@ -58,7 +58,7 @@ from rl_adn import PowerNetEnv, make_env_config
 
 config = make_env_config(node=34, topology_scenario="TP4", return_graph=True)
 env = PowerNetEnv(config)
-state, info = env.reset(return_info=True)
+state, info = env.reset(seed=2026)
 print(info["topology_scenario"])
 ```
 
@@ -72,7 +72,7 @@ config = make_env_config(
     return_graph=True,
 )
 env = PowerNetEnv(config)
-state, info = env.reset(return_info=True)
+state, info = env.reset(seed=2026)
 ```
 
 Inspect the active topology for later GNN work:
@@ -84,6 +84,27 @@ graph = env.get_graph_data()
 
 `metadata` includes feeder id, scenario id, node count, edge count, and active edges. `graph` returns plain NumPy/Python structures such as adjacency and edge index.
 
+## Public API
+
+The stable package surface is:
+
+- `Battery`
+- `BatteryConfig`
+- `EnvConfig`
+- `TopologyConfig`
+- `GeneralPowerDataManager`
+- `PowerNetEnv`
+- `make_env_config(...)`
+
+`make_env_config(...)` now returns a typed `EnvConfig` dataclass rather than a loose dictionary.
+
+`PowerNetEnv` follows Gymnasium semantics:
+
+```python
+obs, info = env.reset(seed=2026)
+next_obs, reward, terminated, truncated, info = env.step(action)
+```
+
 ## Repository Structure
 
 - `rl_adn/`: package source code
@@ -93,7 +114,7 @@ graph = env.get_graph_data()
 
 ## Highlights
 
-- Flexible active distribution network environment modeling
+- Gymnasium-style active distribution network environment
 - Laurent power flow solver for faster training-time simulation
 - DRL algorithms and optimization baselines in the same repository
 - Bundled network and time-series datasets for reproducible experiments
@@ -107,9 +128,9 @@ The library was originally released alongside the RL-ADN research paper on optim
 ## Recommended Learning Path
 
 1. Run `examples/quickstart_env.py` for the minimal package-backed environment flow.
-2. Open `examples/Customize_env.ipynb` to understand configuration customization.
-3. Open the DDPG training notebook once the environment baseline is clear.
-4. Try fixed and pooled topology scenarios before moving on to GNN-based experiments.
+2. Read the typed config surface through `rl_adn.make_env_config(...)`.
+3. Try fixed and pooled topology scenarios before moving on to GNN-based experiments.
+4. Use notebooks only as supplementary material after the script workflow is clear.
 
 ## Current Limits
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -12,43 +12,38 @@
 #
 
 
-
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
 
+sys.path.insert(0, os.path.abspath(".."))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'RL-ADN'
-copyright = '2023, Shengren'
-author = 'Shengren'
+project = "RL-ADN"
+copyright = "2023, Shengren"
+author = "Shengren"
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.coverage',
-    'sphinx.ext.napoleon'
-]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.coverage", "sphinx.ext.napoleon"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 autodoc_default_options = {
-    'show-inheritance': True,
+    "show-inheritance": True,
 }
-autodoc_mock_imports = ['gym', 'pandapower', 'pandapower.topology', 'psutil']
+autodoc_mock_imports = ["gym", "pandapower", "pandapower.topology", "psutil", "pyomo", "pyomo.environ"]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -57,7 +52,7 @@
 # a list of builtin themes.
 #
 # html_theme = 'alabaster'
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 
 # Add any paths that contain custom static files (such as style sheets) here,

diff --git a/docs/modules.rst b/docs/modules.rst
@@ -5,11 +5,9 @@ rl_adn
    :maxdepth: 4
 
    rl_adn
-   rl_adn.data_manager
+   rl_adn.data
    rl_adn.data_sources
-   rl_adn.data_sources.network_data
-   rl_adn.data_sources.time_series_data
-   rl_adn.DRL_algorithms
+   rl_adn.algorithms
    rl_adn.environments
-   rl_adn.utility
-   rl_adn.benckmark_algorithms
+   rl_adn.network
+   rl_adn.benchmarks
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1 +1 @@
--r ../requirements-dev.txt
+-e ..[dev]
diff --git a/docs/rl_adn.DRL_algorithms.rst b/docs/rl_adn.DRL_algorithms.rst
diff --git a/docs/rl_adn.DRL_algorithms.Agent.rst → docs/rl_adn.algorithms.Agent.rst b/docs/rl_adn.DRL_algorithms.Agent.rst → docs/rl_adn.algorithms.Agent.rst
@@ -1,7 +1,7 @@
-rl_adn.DRL_algorithms.Agent module
+rl_adn.algorithms.Agent module
 ==================================
 
-.. automodule:: rl_adn.DRL_algorithms.Agent
+.. automodule:: rl_adn.algorithms.Agent
    :members:
    :show-inheritance:
    :no-index:
diff --git a/docs/rl_adn.DRL_algorithms.DDPG.rst → docs/rl_adn.algorithms.DDPG.rst b/docs/rl_adn.DRL_algorithms.DDPG.rst → docs/rl_adn.algorithms.DDPG.rst
@@ -1,7 +1,7 @@
-rl_adn.DRL_algorithms.DDPG module
+rl_adn.algorithms.DDPG module
 =================================
 
-.. automodule:: rl_adn.DRL_algorithms.DDPG
+.. automodule:: rl_adn.algorithms.DDPG
    :members:
    :show-inheritance:
    :no-index:
diff --git a/docs/rl_adn.DRL_algorithms.SAC.rst → docs/rl_adn.algorithms.PPO.rst b/docs/rl_adn.DRL_algorithms.SAC.rst → docs/rl_adn.algorithms.PPO.rst
@@ -1,7 +1,7 @@
-rl_adn.DRL_algorithms.SAC module
+rl_adn.algorithms.PPO module
 ================================
 
-.. automodule:: rl_adn.DRL_algorithms.SAC
+.. automodule:: rl_adn.algorithms.PPO
    :members:
    :show-inheritance:
    :no-index:
diff --git a/docs/rl_adn.DRL_algorithms.TD3.rst → docs/rl_adn.algorithms.SAC.rst b/docs/rl_adn.DRL_algorithms.TD3.rst → docs/rl_adn.algorithms.SAC.rst
@@ -1,7 +1,7 @@
-rl_adn.DRL_algorithms.TD3 module
+rl_adn.algorithms.SAC module
 ================================
 
-.. automodule:: rl_adn.DRL_algorithms.TD3
+.. automodule:: rl_adn.algorithms.SAC
    :members:
    :show-inheritance:
    :no-index:
diff --git a/docs/rl_adn.DRL_algorithms.PPO.rst → docs/rl_adn.algorithms.TD3.rst b/docs/rl_adn.DRL_algorithms.PPO.rst → docs/rl_adn.algorithms.TD3.rst
@@ -1,7 +1,7 @@
-rl_adn.DRL_algorithms.PPO module
+rl_adn.algorithms.TD3 module
 ================================
 
-.. automodule:: rl_adn.DRL_algorithms.PPO
+.. automodule:: rl_adn.algorithms.TD3
    :members:
    :show-inheritance:
    :no-index:
diff --git a/docs/rl_adn.algorithms.rst b/docs/rl_adn.algorithms.rst
@@ -0,0 +1,15 @@
+rl_adn.algorithms package
+=============================
+
+Algorithm modules are documented on dedicated subpages to avoid duplicate
+autodoc entries while preserving the full module tree.
+
+.. toctree::
+   :maxdepth: 2
+
+   rl_adn.algorithms.Agent
+   rl_adn.algorithms.DDPG
+   rl_adn.algorithms.PPO
+   rl_adn.algorithms.SAC
+   rl_adn.algorithms.TD3
+   rl_adn.algorithms.utility
diff --git a/docs/rl_adn.DRL_algorithms.utility.rst → docs/rl_adn.algorithms.utility.rst b/docs/rl_adn.DRL_algorithms.utility.rst → docs/rl_adn.algorithms.utility.rst
@@ -1,8 +1,8 @@
-rl_adn.DRL_algorithms.utility module
+rl_adn.algorithms.utility module
 ====================================
 
 The utility module remains part of the docs tree, but member-level autodoc is
 deferred until its legacy docstrings are normalized.
 
-.. automodule:: rl_adn.DRL_algorithms.utility
+.. automodule:: rl_adn.algorithms.utility
    :show-inheritance:
diff --git a/docs/rl_adn.benchmarks.rst b/docs/rl_adn.benchmarks.rst
@@ -0,0 +1,7 @@
+rl_adn.benchmarks package
+====================================
+
+.. automodule:: rl_adn.benchmarks
+   :members:
+   :show-inheritance:
+
diff --git a/docs/rl_adn.benckmark_algorithms.rst b/docs/rl_adn.benckmark_algorithms.rst
diff --git a/docs/rl_adn.data_manager.rst → docs/rl_adn.data.rst b/docs/rl_adn.data_manager.rst → docs/rl_adn.data.rst
@@ -1,8 +1,8 @@
-rl_adn.data_manager package
+rl_adn.data package
 ===========================
 
 The stable public entrypoint for the data manager is documented below.
 
-.. automodule:: rl_adn.data_manager.data_manager
+.. automodule:: rl_adn.data.manager
    :members:
    :show-inheritance:
diff --git a/docs/rl_adn.environments.rst b/docs/rl_adn.environments.rst
@@ -7,7 +7,19 @@ The package-level exports mirror the core environment entrypoints documented bel
    :members:
    :show-inheritance:
 
-.. automodule:: rl_adn.environments.config
+.. automodule:: rl_adn.config
+   :members:
+   :show-inheritance:
+
+.. automodule:: rl_adn.environments.observation
+   :members:
+   :show-inheritance:
+
+.. automodule:: rl_adn.environments.reward
+   :members:
+   :show-inheritance:
+
+.. automodule:: rl_adn.environments.solvers
    :members:
    :show-inheritance:
 

diff --git a/docs/rl_adn.utility.rst → docs/rl_adn.network.rst b/docs/rl_adn.utility.rst → docs/rl_adn.network.rst
@@ -1,15 +1,15 @@
-rl_adn.utility package
+rl_adn.network package
 ======================
 
 Utility submodules are documented individually to avoid duplicating package-level aliases.
 
-.. automodule:: rl_adn.utility.grid
+.. automodule:: rl_adn.network.grid
    :show-inheritance:
 
-.. automodule:: rl_adn.utility.numbarize
+.. automodule:: rl_adn.network.numbarize
    :members:
    :show-inheritance:
 
-.. automodule:: rl_adn.utility.utils
+.. automodule:: rl_adn.network.utils
    :members:
    :show-inheritance:
diff --git a/examples/Tutorial_DDPG_training_using_RL_ADN.ipynb b/examples/Tutorial_DDPG_training_using_RL_ADN.ipynb
@@ -69,8 +69,8 @@
    "source": [
     "import torch\n",
     "from torch.nn.utils import clip_grad_norm_\n",
-    "from rl_adn.DRL_algorithms.Agent import AgentDDPG\n",
-    "from rl_adn.DRL_algorithms.utility import Config, ReplayBuffer, SumTree, build_mlp, get_episode_return, get_optim_param\n",
+    "from rl_adn.algorithms.Agent import AgentDDPG\n",
+    "from rl_adn.algorithms.utility import Config, ReplayBuffer, SumTree, build_mlp, get_episode_return, get_optim_param\n",
     "import time"
    ],
    "metadata": {