Skip to content

CLAUDE.md

Latest commit

 

History

History
122 lines (90 loc) · 4.58 KB

CLAUDE.md

File metadata and controls

122 lines (90 loc) · 4.58 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

Running Tests

# Run all tests (excluding GPU tests by default)
pytest

# Run tests with coverage
pytest --cov=./ --cov-report=xml linopy --doctest-modules test

# Run a specific test file
pytest test/test_model.py

# Run a specific test function
pytest test/test_model.py::test_model_creation

# Run GPU tests (requires GPU hardware and cuPDLPx installation)
pytest --run-gpu

# Run only GPU tests
pytest -m gpu --run-gpu

GPU Testing: Tests that require GPU hardware (e.g., cuPDLPx solver) are automatically skipped by default since CI machines typically don't have GPUs. To run GPU tests locally, use the --run-gpu flag. The tests are automatically marked with @pytest.mark.gpu based on solver capabilities.

Linting and Type Checking

# Run linter (ruff)
ruff check .
ruff check --fix .  # Auto-fix issues

# Run formatter
ruff format .

# Run type checker
mypy .

# Run all pre-commit hooks
pre-commit run --all-files

Development Setup

# Create virtual environment and install development dependencies
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install uv
uv pip install -e .[dev,solvers]

High-Level Architecture

linopy is a linear optimization library built on top of xarray, providing N-dimensional labeled arrays for variables and constraints. The architecture follows these key principles:

Core Components

  1. Model (model.py): Central container for optimization problems

    • Manages variables, constraints, and objective
    • Handles solver integration through abstract interfaces
    • Supports chunked operations for memory efficiency
    • Provides matrix representations for solver APIs

  2. Variables (variables.py): Multi-dimensional decision variables

    • Built on xarray.Dataset with labels, lower, and upper bounds
    • Arithmetic operations automatically create LinearExpressions
    • Support for continuous and binary variables
    • Container class (Variables) manages collections with dict-like access

  3. Constraints (constraints.py): Linear inequality/equality constraints

    • Store coefficients, variable references, signs, and RHS values
    • Support ≤, ≥, and = constraints
    • Container class (Constraints) provides organized access

  4. Expressions (expressions.py): Linear combinations of variables

    • LinearExpression: coeffs × vars + const
    • QuadraticExpression: for non-linear optimization
    • Support full arithmetic operations with automatic broadcasting
    • Special _term dimension for handling multiple terms

  5. Solvers (solvers.py): Abstract interface with multiple implementations

    • File-based solvers: Write LP/MPS files, call solver, parse results
    • Direct API solvers: Use Python bindings (e.g., gurobipy)
    • Automatic solver detection based on installed packages

Data Flow Pattern

  1. User creates Model and adds Variables with coordinates (dimensions)
  2. Variables combined into LinearExpressions through arithmetic
  3. Expressions used to create Constraints and Objective
  4. Model.solve() converts to solver format and retrieves solution
  5. Solution stored back in xarray format with original dimensions

Key Design Patterns

  • xarray Integration: All data structures use xarray for dimension handling
  • Lazy Evaluation: Expressions built symbolically before solving
  • Broadcasting: Operations automatically align dimensions
  • Solver Abstraction: Clean separation between model and solver specifics
  • Memory Efficiency: Support for dask arrays and chunked operations

When modifying the codebase, maintain consistency with these patterns and ensure new features integrate naturally with the xarray-based architecture.

Working with the Github Repository

  • The main branch is master.
  • Always create a feature branch for new features or bug fixes.
  • Use the github cli (gh) to interact with the Github repository.

Development Guidelines

  1. Always write tests for new features or bug fixes.
  2. Always run the tests after making changes and ensure they pass.
  3. Always use ruff for linting and formatting, run ruff check --fix . to auto-fix issues.
  4. Use type hints and mypy for type checking.
  5. Always write tests into the test directory, following the naming convention test_*.py.
  6. Always write temporary and non git-tracked code in the dev-scripts directory.
  7. In test scripts use linopy assertions from the testing.py module where useful (assert_linequal, assert_varequal, etc.)