pyproject.toml

[build-system]
build-backend = "hatchling.build"
requires = [ "hatch-vcs", "hatchling" ]

[project]
name = "pylcm"
description = "Specification, solution, and simulation of finite-horizon dynamic choice models."
keywords = [
  "Dynamic programming",
  "Econometrics",
  "Economics",
  "Estimation",
  "Life cycle models",
  "Statistics",
]
requires-python = ">=3.14"
classifiers = [
  "Development Status :: 3 - Alpha",
  "Intended Audience :: Science/Research",
  "License :: OSI Approved :: Apache Software License",
  "Operating System :: MacOS :: MacOS X",
  "Operating System :: Microsoft :: Windows",
  "Operating System :: POSIX",
  "Operating System :: Unix",
  "Programming Language :: Python :: 3 :: Only",
  "Programming Language :: Python :: 3.14",
  "Topic :: Scientific/Engineering",
  "Typing :: Typed",
]
dynamic = [ "version" ]
dependencies = [
  "beartype>=0.21",
  "cloudpickle>=3.1.2",
  # Require the beartype fix, replace once release is there
  # "dags>=0.6.0",
  "h5py>=3.12",
  "jax>=0.11",
  "jaxtyping>=0.3.10",
  "orbax-checkpoint>=0.11",
  "pandas",
  "portion>=2.6",
  "pyarrow",
]
[[project.authors]]
name = "Tim Mensinger"
email = "mensingertim@gmail.com"

[[project.authors]]
name = "Maximilian Jahn"

[[project.authors]]
name = "Janos Gabler"

[[project.authors]]
name = "Hans-Martin von Gaudecker"
email = "hmgaudecker@uni-bonn.de"
[project.license]
file = "LICENSE"
[[project.maintainers]]
name = "Tim Mensinger"
email = "mensingertim@gmail.com"

[[project.maintainers]]
name = "Hans-Martin von Gaudecker"
email = "hmgaudecker@uni-bonn.de"
[project.readme]
content-type = "text/markdown"
file = "README.md"
[project.urls]
Github = "https://github.com/opensourceeconomics/pylcm"
Repository = "https://github.com/opensourceeconomics/pylcm"
Tracker = "https://github.com/opensourceeconomics/pylcm/issues"

[tool.hatch]
version.source = "vcs"
metadata.allow-direct-references = true
build.hooks.vcs.version-file = "src/_lcm/version.py"
build.targets.sdist.exclude = [ "tests" ]
build.targets.sdist.only-packages = true
build.targets.wheel.only-include = [ "src" ]
build.targets.wheel.sources = [ "src" ]

[tool.pixi.dependencies]
asv = "*"
python = "~=3.14.0"
cloudpickle = ">=3.1.2,<4"
h5py = ">=3.12"
jupyterlab = "*"
memory_profiler = "*"
# Required until numba accepts numpy>=2.5.0
numpy = ">=2.4, <2.5.0"
plotly = ">=6.5"
prek = "*"
pyarrow = "*"
pybaum = "*"
scipy = ">=1.16"
snakeviz = "*"
[tool.pixi.environments]
benchmarks-cuda12 = { features = [ "benchmarks", "cuda12" ], solve-group = "cuda12" }
cuda12 = { features = [ "cuda12" ], solve-group = "cuda12" }
cuda13 = { features = [ "cuda13" ], solve-group = "cuda13" }
docs = { features = [ "docs" ], solve-group = "default" }
metal = { features = [ "metal" ], solve-group = "metal" }
tests-cpu = { features = [ "tests" ], solve-group = "default" }
tests-cuda12 = { features = [ "tests", "cuda12" ], solve-group = "cuda12" }
tests-cuda13 = { features = [ "tests", "cuda13" ], solve-group = "cuda13" }
tests-metal = { features = [ "tests", "metal" ], solve-group = "metal" }
type-checking = { features = [ "type-checking", "tests" ], solve-group = "default" }
[tool.pixi.feature.benchmarks.pypi-dependencies]
# Pinned to the aca-model version this solver-seam work is developed against
# (feat/dcegm-solver: main's audit fixes + the DC-EGM solver + smooth-share
# eligibility); flip back to branch = "main" once both sides have merged.
aca-model = { git = "https://github.com/OpenSourceEconomics/aca-model.git", rev = "54fb8df1f83865eee421a4b656676ce4e6787928" }
[tool.pixi.feature.cuda12]
platforms = [ "linux-64-cuda12" ]
[tool.pixi.feature.cuda12.target.linux-64.dependencies]
cuda-nvcc = "~=12.0"
[tool.pixi.feature.cuda12.target.linux-64.pypi-dependencies]
jax = { version = ">=0.11", extras = [ "cuda12" ] }
[tool.pixi.feature.cuda13]
platforms = [ "linux-64-cuda13" ]
[tool.pixi.feature.cuda13.target.linux-64.dependencies]
cuda-nvcc = "~=13.0"
[tool.pixi.feature.cuda13.target.linux-64.pypi-dependencies]
jax = { version = ">=0.11", extras = [ "cuda13" ] }
[tool.pixi.feature.docs.dependencies]
jupyter-book = ">=2.0"
mystmd = "*"
[tool.pixi.feature.docs.pypi-dependencies]
quantecon = "*"
[tool.pixi.feature.docs.tasks]
build-docs = { cmd = "jupyter book build --html --execute", cwd = "docs", env = { JAX_PLATFORMS = "cpu" } }
explanation-notebooks = "jupyter execute docs/explanations/*.ipynb"
view-docs = { cmd = "jupyter book start --execute", cwd = "docs", env = { JAX_PLATFORMS = "cpu" } }
[tool.pixi.feature.metal]
platforms = [ "osx-arm64" ]
[tool.pixi.feature.metal.target.osx-arm64.pypi-dependencies]
jax = ">=0.11"
jax-metal = ">=0.1.1"
[tool.pixi.feature.tests.dependencies]
pytest = "*"
pytest-cov = "*"
pytest-xdist = "*"
[tool.pixi.feature.tests.pypi-dependencies]
quantecon = "*"
[tool.pixi.feature.tests.tasks]
tests = "pytest tests"
tests-32bit = "pytest tests --precision=32"
tests-with-cov = "pytest tests --cov-report=xml --cov=./"
[tool.pixi.feature.type-checking.dependencies]
# The env ty analyzes against (`[tool.ty] environment.python`); the ty binary
# itself is managed by the `ty` pre-commit hook (`prek run ty --all-files`).
matplotlib = "*"
pandas-stubs = "*"
scipy-stubs = "*"
[tool.pixi.pypi-dependencies]
jax = ">=0.11"
pdbp = "*"
pylcm = { path = ".", editable = true }
# Remove and comment in `dags >= 0.6.0` above once released.
dags = { git = "https://github.com/OpenSourceEconomics/dags.git", branch = "main" }
[tool.pixi.tasks]
asv-compare = "asv compare"
asv-preview = "asv preview"
asv-pr-comment = "python benchmarks/pr_comment.py"
asv-publish = "python benchmarks/publish.py"
asv-quick = { cmd = "asv run --quick --set-commit-hash=$(git rev-parse HEAD)", env = { XLA_PYTHON_CLIENT_PREALLOCATE = "false" } }
asv-run = { cmd = 'git status --porcelain --ignore-submodules | grep -q . && echo "Refusing to benchmark: worktree is dirty. Commit first." && exit 1; asv run -v --show-stderr --set-commit-hash=$(git rev-parse HEAD)', env = { XLA_PYTHON_CLIENT_PREALLOCATE = "false" } }
asv-run-and-pr-comment = { depends-on = [ "asv-run", "asv-pr-comment" ] }
asv-run-and-publish-main = { depends-on = [ "asv-run", "asv-publish" ] }
[tool.pixi.workspace]
channels = [ "conda-forge" ]
platforms = [
  "linux-64",
  "osx-arm64",
  "win-64",
  { name = "linux-64-cuda12", platform = "linux-64", cuda = "12" },
  { name = "linux-64-cuda13", platform = "linux-64", cuda = "13" },
]

[tool.ruff]
target-version = "py314"
exclude = [ "src/lcm/sandbox" ]
fix = true
unsafe-fixes = false
[tool.ruff.lint]
select = [ "ALL" ]
extend-ignore = [
  "COM812",  # Conflicts with ruff-format
  "CPY001",  # Missing copyright notice
  "D",       # Docstrings
  "EM101",   # Exception must not use a string literal
  "EM102",   # Exception must not use an f-string literal
  "FIX002",  # Line contains TODO
  "ISC001",  # Conflicts with ruff-format
  "N802",    # Function name should be lowercase
  "N803",    # Argument name should be lowercase
  "N806",    # Variable in function should be lowercase
  "N815",    # Variable in class scope should not be mixedCase
  "PLR0913", # Too many arguments in function definition
  "PLR0917", # Too many positional arguments
  "TC001",   # Move application import into a type-checking block
  "TC002",   # Move third-party import into a type-checking block
  "TC003",   # Move standard library import into a type-checking block
  "TRY003",  # Long messages outside exception class
  "UP047",   # Generic function should use type parameters
  "F722",    # https://docs.kidger.site/jaxtyping/faq/#flake8-or-ruff-are-throwing-an-error
]
per-file-ignores."benchmarks/*" = [
  "ANN",     # Annotations
  "ARG002",  # Unused method argument (ASV passes params to all methods)
  "BLE001",  # Blind exception
  "D",       # Docstrings
  "INP001",  # Implicit namespace package
  "PLC0415", # import not at top level
  "PLR2004", # Magic values in comparison
  "PLW1510", # subprocess.run without explicit check
  "RUF012",  # Mutable class attribute (ASV requires list `params`/`param_names`)
  "S101",    # Use of assert
  "SIM108",  # Ternary operator
  "S603",    # subprocess call without shell=True check
  "S607",    # Partial executable path
  "T201",    # print found
]
per-file-ignores."docs/**/*" = [
  "ANN001", # Missing type annotation for function argument
  "ANN002", # Missing type annotation for *args
  "ANN003", # Missing type annotation for **kwargs
  "ANN201", # Missing return type annotation for public function
  "ANN202", # Missing return type annotation for private function
  "ARG001", # Unused function argument
  "D100",   # Missing docstring in public module
  "D103",   # Missing docstring in public function
  "D104",   # Missing docstring in public package
  "PD011",  # Use `.to_numpy()` — false positive on JAX .values
  "S101",   # Use of assert
  "RUF001", # Ambiguous Unicode characters (Greek letters in plot titles)
  "T201",   # print found
  "T203",   # pprint found
]
per-file-ignores."explanations/*" = [
  "ANN",    # Annotations
  "E402",   # Module level import not at top of file
  "INP001", # Implicit namespace package
  "T201",   # print found
  "T203",   # pprint found
]
per-file-ignores."src/_lcm/utils/functools.py" = [
  "ANN401", # Dynamically typed expressions (Any)
]
per-file-ignores."src/_lcm/**/*[A-Z]*.py" = [
  "N999", # Module name mixing uppercase and lowercase (Q_and_F.py, V.py, max_Q_over_a.py)
]
per-file-ignores."src/lcm_examples/mahler_yum_2024/**" = [
  "PD008", # false positive on JAX `.at[].set()` immutable updates
  "PD011", # false positive on `AgeGrid.values`
]
per-file-ignores."tests/*" = [
  "ANN",     # Annotations
  "D",       # Docstrings
  "INP001",  # Implicit namespace package
  "N999",    # Module name mixing uppercase and lowercase
  "PLR2004", # Magic values in comparison
  "S101",    # Use of assert
  "S301",    # Use of pickle
  "SLF001",  # Private member access
]
per-file-ignores."tests/test_certainty_equivalent.py" = [
  "ARG001", # Unused function argument (x64_enabled / x64_disabled fixtures)
]
per-file-ignores."tests/test_koopmans_aggregation.py" = [
  "ARG001", # Unused function argument (x64_enabled fixture)
]
per-file-ignores."tests/test_compilation_cache.py" = [
  "S603", # subprocess call with test-controlled input
]
per-file-ignores."tests/test_dtypes.py" = [
  "ARG001", # Unused function argument (x64_enabled / x64_disabled fixtures)
]
per-file-ignores."tests/test_explicit_dtype_filter.py" = [
  "ARG001", # Unused function argument (x64_disabled fixture)
]
per-file-ignores."tests/test_float_dtype_invariants.py" = [
  "ARG001", # Unused function argument (x64_disabled fixture)
]
per-file-ignores."tests/test_next_state.py" = [
  "ARG001", # Unused function argument
  "ARG005", # Unused lambda argument
  "E731",   # Do not assign a `lambda` expression, use a `def`
]
per-file-ignores."tests/test_Q_and_F.py" = [
  "ARG001", # Unused function argument
  "ARG005", # Unused lambda argument
  "E731",   # Do not assign a `lambda` expression, use a `def`
]
pydocstyle.convention = "google"
[tool.ruff.lint.flake8-bugbear]
extend-immutable-calls = [
  "_lcm.certainty_equivalent.LinearExpectation",
  "_lcm.utils.containers.Unset",
  "lcm.LinearExpectation",
  "lcm.LinearAggregator",
  "lcm.certainty_equivalent.LinearExpectation",
  "lcm.koopmans_aggregation.LinearAggregator",
  "LinearAggregator",
  "LinearExpectation",
  "Unset",
]
[tool.ruff.lint.isort]
known-first-party = [ "_lcm", "lcm", "lcm_examples", "tests" ]

[tool.pyproject-fmt]
column_width = 88
max_supported_python = "3.14"
table_format = "long"
expand_tables = [
  "tool.pixi.dependencies",
  "tool.pixi.environments",
  "tool.pixi.feature.tests.pypi-dependencies",
  "tool.pixi.feature.tests.tasks",
  "tool.pixi.feature.type-checking.dependencies",
  "tool.pixi.pypi-dependencies",
  "tool.pixi.tasks",
  "tool.pixi.workspace",
]
collapse_tables = [ "tool.hatch", "tool.pytask", "tool.pytest", "tool.ty" ]

[tool.ty]
src.include = [ "docs/", "src/", "tests/" ]
# ty resolves third-party imports from this pixi env (the ty-pre-commit hook runs
# `uv check --no-project`, so uv neither creates a `.venv` nor resolves deps). Run
# `pixi install` once.
environment.python = ".pixi/envs/type-checking"
rules.ambiguous-protocol-member = "error"
rules.deprecated = "error"
rules.division-by-zero = "error"
rules.ignore-comment-unknown-rule = "error"
rules.ineffective-final = "error"
rules.invalid-enum-member-annotation = "error"
rules.invalid-ignore-comment = "error"
rules.invalid-legacy-positional-parameter = "error"
rules.redundant-cast = "error"
rules.unused-awaitable = "error"
rules.unused-ignore-comment = "error"

[tool.pytest]
ini_options.norecursedirs = [ "docs" ]
ini_options.addopts = [
  "--pdbcls=pdbp:Pdb",
  "--dist",
  "loadfile",
]
ini_options.markers = [
  "gpu: Tests that require a GPU (skipped on CPU-only machines)",
  "illustrative: Tests are designed for illustrative purposes",
]
ini_options.filterwarnings = [
  # JAX emits this UserWarning when user code asks for a dtype wider
  # than the active x64 setting allows. Under `--precision=32` it
  # surfaces every stray `jnp.int64` / `jnp.float64` / `dtype=int64`
  # literal in src/ — the only files that legitimately trigger it are
  # the dtype-invariant test modules, which opt out via a local
  # `pytestmark` filter.
  "error:Explicitly requested dtype.*:UserWarning",
]

[tool.yamlfix]
line_length = 88
none_representation = "null"
sequence_style = "block_style"