Development Guide¶

This guide is for contributors and advanced users who want to understand LumiX’s architecture and extend its functionality.

Development Topics

Overview¶

LumiX is built with several key principles:

Type Safety: Extensive use of Python’s type system
Data-Driven: Models built from data, not loops
Solver Agnostic: Unified interface to multiple solvers
Fluent API: Method chaining for readability
Automatic Expansion: Variable/constraint families expand during solving

Target Audience¶

This guide is for:

Contributors to LumiX
Advanced users building extensions
Researchers customizing the library
Anyone curious about the internals

Getting Started¶

Clone and Install¶

git clone https://github.com/tdelphi1981/LumiX.git
cd LumiX
pip install -e .[dev]

Run Tests¶

pytest

Type Check¶

mypy src/lumix

Code Style¶

black src/lumix
ruff check src/lumix

Module Overview¶

        graph TD
    A[core] --> B[solvers]
    A --> C[analysis]
    A --> D[linearization]
    A --> E[goal_programming]
    F[indexing] --> A
    G[nonlinear] --> D
    H[solution] --> B
    I[utils] --> A

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#ffe1e1
    style D fill:#e1ffe1
    style E fill:#f0e1ff

Core Modules:

core: Model building (variables, constraints, expressions, models) (documented)
solvers: Solver interfaces (OR-Tools, Gurobi, CPLEX, GLPK, CP-SAT) (documented)
indexing: Multi-dimensional indexing utilities (documented)
nonlinear: Non-linear term definitions (documented)
linearization: Automatic linearization engine (documented)
utils: Logging, ORM, rational conversion (documented)
solution: Solution handling and mapping (documented)
analysis: Sensitivity, scenario, what-if analysis (documented)
goal_programming: Multi-objective optimization

Core Module Documentation¶

Deep dive into the core module’s architecture and extensibility:

Core Architecture - Core module design patterns and architecture
Extending Core Components - How to extend core components
Design Decisions - Design decisions and trade-offs

Solvers Module Documentation¶

Understand solvers architecture and how to add new solver implementations:

Solvers Architecture - Solvers module design patterns and architecture
Extending Solvers - How to implement custom solvers

Indexing Module Documentation¶

Understand indexing architecture and customization:

Indexing Architecture - Indexing module design patterns and architecture
Extending Indexing - How to create custom dimensions and products

Nonlinear Module Documentation¶

Learn about nonlinear term definitions and how to extend them:

Nonlinear Module Architecture - Nonlinear module design patterns and architecture
Extending Nonlinear Module - How to create custom nonlinear term types

Utils Module Documentation¶

Learn about utils module architecture and how to extend it:

Utils Module Architecture - Utils module design patterns and architecture
Extending Utils Components - How to extend and customize utils components

Linearization Module Documentation¶

Understand linearization architecture and customization:

Linearization Architecture - Linearization module design patterns and architecture
Extending Linearization - How to create custom linearization techniques

Solution Module Documentation¶

Learn about solution handling architecture and customization:

Solution Module Architecture - Solution module design patterns and architecture
Extending Solution Components - How to create custom solution classes and mappers

Analysis Module Documentation¶

Learn about analysis tools architecture and customization:

Analysis Architecture - Analysis module design patterns and architecture
Extending Analysis - How to create custom analyzers and analysis types

Goal Programming Module Documentation¶

Learn about goal programming architecture and customization:

Goal Programming Architecture - Goal programming module design patterns and architecture
Extending Goal Programming - How to create custom goal types, relaxation strategies, and objective builders

Next Steps¶

For Core Module Development:

Core Architecture - Deep dive into core module design
Extending Core Components - How to extend core components
Design Decisions - Why things work the way they do

For Solvers Module Development:

Solvers Architecture - Solvers module architecture and patterns
Extending Solvers - How to implement custom solver interfaces

For Indexing Module Development:

Indexing Architecture - Indexing module architecture and patterns
Extending Indexing - Custom dimensions, products, and filters

For Nonlinear Module Development:

Nonlinear Module Architecture - Nonlinear module architecture and patterns
Extending Nonlinear Module - Custom nonlinear term types and linearization

For Utils Module Development:

Utils Module Architecture - Utils module architecture details
Extending Utils Components - Custom loggers, protocols, and converters

For Linearization Module Development:

Linearization Architecture - Linearization module architecture and patterns
Extending Linearization - Custom linearization techniques and formulations

For Solution Module Development:

Solution Module Architecture - Solution module architecture and patterns
Extending Solution Components - Custom solution classes, mappers, and validators

For Analysis Module Development:

Analysis Architecture - Analysis module architecture and patterns
Extending Analysis - Custom analyzers and analysis workflows

For Goal Programming Module Development:

Goal Programming Architecture - Goal programming module architecture and patterns
Extending Goal Programming - Custom goal types, relaxation strategies, and objective builders