InfraLib: Infrastructure Management for RL and Optimization

InfraLib is a comprehensive Python library for modeling, simulating, and analyzing large-scale infrastructure management problems. It provides a realistic and granular representation of infrastructure systems by integrating hierarchical models that capture intricate relationships between components and facilities.

Introduction

Infrastructure systems are the backbone of modern society, encompassing transportation networks, utility systems, and public facilities. Managing these systems efficiently is crucial for economic stability, environmental sustainability, and public safety. InfraLib addresses the complex challenges of infrastructure management by providing:

  • Stochastic deterioration modeling with partial observability

  • Gymnasium-compatible RL environments for algorithm development

  • Scalable simulation supporting millions of components

  • Rich visualization and analysis tools

  • Flexible model architecture with dependency injection

  • Web-based human interface for expert data collection

Installation

Install InfraLib using pip:

pip install infralib

Or install from source:

git clone https://github.com/pthangeda/InfraLib.git
cd InfraLib
pip install -e .

Requirements:

  • Python 3.12+

  • NumPy >= 1.25.2

  • SciPy >= 1.10.0

  • Gymnasium >= 1.0.0

  • Stable-Baselines3 >= 2.0.0

  • Additional dependencies listed in pyproject.toml

Quick Start

Here’s a simple example to get you started with InfraLib:

from infralib.models.dynamics import WeibullDynamics
from infralib.models.cost import SimpleCost
from infralib.models.budget import FixedBudget
from infralib.simulator import Simulator
import numpy as np

# Setup models
dynamics = WeibullDynamics(n_states=10)
cost = SimpleCost()
budget = FixedBudget(initial_budget=10000)

# Create and run simulator
sim = Simulator(dynamics, cost, budget)
sim.reset(n_components=5)
actions = np.array([0, 1, 2, 0, 1])  # do_nothing, inspect, repair, do_nothing, inspect
states, info = sim.step(actions)

print(f"Total cost: {info['total_cost']:.2f}")
print(f"Failures: {info['failures']}")

For RL training:

from infralib.envs.simple import SimpleInfraEnv
import stable_baselines3 as sb3

# Create environment
env = SimpleInfraEnv(n_components=5, max_budget=10000)

# Train RL agent
model = sb3.PPO('MlpPolicy', env, verbose=1)
model.learn(total_timesteps=100000)

# Evaluate policy
obs, info = env.reset()
for _ in range(100):
    action, _states = model.predict(obs)
    obs, reward, done, truncated, info = env.step(action)
    if done or truncated:
        obs, info = env.reset()

Key Features

Stochastic Deterioration Modeling

InfraLib models infrastructure component deterioration using:

  • Weibull dynamics: Realistic deterioration patterns based on empirical data

  • Markov dynamics: Simplified models for rapid prototyping

  • Custom dynamics: Extensible framework for domain-specific models

Partial Observability

Real-world infrastructure management involves:

  • Noisy inspections: Component states are not directly observable

  • Inspection costs: Gathering information requires resources

  • Belief state management: Agents must reason under uncertainty

Gymnasium Compatibility

InfraLib provides RL environments that are:

  • Fully compatible with Stable-Baselines3 and other RL libraries

  • Configurable observation spaces: Full, partial, or custom observations

  • Flexible reward functions: Customize objectives for your use case

  • Vectorized environments: Train multiple agents in parallel

Scalability

InfraLib is designed for real-world scale:

  • Millions of components: Efficient vectorized operations with Numba

  • Long time horizons: Simulate years of infrastructure evolution

  • Batch policy evaluation: Compare multiple strategies efficiently

Support and Community

Contact: Pranay Thangeda or Melkior Ornik

Email: We welcome questions, bug reports, and feature requests. Please contact Pranay Thangeda (pranayt2@illinois.edu) or Melkior Ornik (melkior.ornik@illinois.edu) directly for support and collaboration opportunities.

Feature Requests: We are actively seeking collaborations and are willing to implement features that help researchers and practitioners use InfraLib for their specific use cases. Please reach out with your requirements and we’ll work with you to extend the library’s capabilities.

Contributing: We welcome contributions from the community. Please see our GitHub repository for contribution guidelines.

Issues: Report bugs and request features on our GitHub issues page: https://github.com/pthangeda/InfraLib/issues

License

InfraLib is released under the MIT License:

MIT License

Copyright (c) 2025 InfraLib Team

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.

API Reference

Contents:

Indices and tables