Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Installation

Prerequisites

pylcm requires Python 3.14+. We recommend pixi or uv for environment management.

Install with pixi

pixi add pylcm

Install with uv

uv add pylcm

Install from GitHub

If you require features not yet in a released version, install from GitHub:

# pixi
pixi add pylcm --pypi --git https://github.com/OpenSourceEconomics/pylcm.git --rev main

# uv
uv add pylcm --git https://github.com/OpenSourceEconomics/pylcm.git --rev main

The compiled kernel, and installing without a C++ compiler

The certified upper envelopes use pylcm’s exact-affine kernel: a small native payload built from source maintained in this repository. It is part of the pylcm installation, not an arbitrary shared library downloaded or discovered at runtime.

How the payload arrives depends on how pylcm is installed:

A CPU library does not satisfy a solve whose current JAX backend is a GPU. Likewise, a payload built for another platform, Python ABI, toolchain, or JAX installation is not a portable substitute. If no compatible wheel exists, the package manager performs the source build and therefore needs the local toolchain.

If the required compiler is missing, a source install fails with a message naming it. To install without the certified capability on purpose, set the explicit build flag:

LCM_SKIP_EXACT_AFFINE=1 pip install pylcm

The build then compiles no exact-affine payload and reports the omitted capability. Any other value, including 0, requests the normal build. A skipped installation can use GridSearch, a typed approximate DCEGM envelope, or NBEGM(envelope_arithmetic="ordinary")—the last also as the inner solver of NNBEGM—under that mode’s approximation contract.

Defaults that request certified arithmetic require a compatible payload and never silently fall back: DCEGM’s ExactEnvelope checks the active backend during Model(...). NBEGM defaults to NBEGM(envelope_arithmetic="ordinary"), which needs no payload; an explicit envelope_arithmetic="certified" requires the same installed payload. If it is absent or unloadable, certified mode fails before returning a certified result and raises ExactAffineKernelUnavailableError. The validation boundary may move earlier; NBEGM never silently falls back. The same requirement applies when it is the inner solver of NNBEGM.

To restore the capability after changing the toolchain or native sources, reinstall pylcm in the target environment; for a pixi development checkout use:

pixi reinstall pylcm

GPU Acceleration (optional, but then this is the whole point of it)

pylcm uses JAX for numerical computation. By default, JAX runs on CPU. For GPU acceleration, install the appropriate JAX variant.

Linux (CUDA)

If you use pixi, add a CUDA feature to your pyproject.toml:

[tool.pixi.feature.cuda13]
platforms = ["linux-64"]
system-requirements = {cuda = "13"}

[tool.pixi.feature.cuda13.target.linux-64.dependencies]
cuda-nvcc = "~=13.0"

[tool.pixi.feature.cuda13.target.linux-64.pypi-dependencies]
jax = {version = ">=0.8", extras = ["cuda13"]}

For CUDA 12, replace cuda13 with cuda12 throughout.

If you use uv:

uv add "jax[cuda13]"

See the JAX installation guide for details on CUDA toolkit requirements.

macOS (Metal)

# pixi
pixi add jax-metal --pypi

# uv
uv add jax-metal

This requires Apple Silicon (M1 or later).

Verify Installation

import lcm
import jax

print(jax.devices())  # Should show GPU if configured

If GPU acceleration is set up correctly, you will see a GpuDevice or MetalDevice in the output. Otherwise, you will see CpuDevice, which is fine for development and smaller models.

JAX Settings

pylcm sets two JAX configuration defaults on import:

Both only apply if you have not already set the variable yourself.

pylcm leaves GPU memory allocation to JAX, which reserves 75% of the device up front. The default device-memory budget is derived from that preallocated pool. To allocate on demand instead, set XLA_PYTHON_CLIENT_PREALLOCATE=false before JAX initialises its backend and pass an explicit ExecutionConfig(device_memory_bytes=...), or None to disable admission; the default budget refuses an on-demand pool (see tuning).

Import order does not matter

JAX reads its environment variables once, while it defines its configuration — so a value exported after import jax never reaches it. pylcm therefore applies both compilation-cache settings through jax.config as well, and they hold whether lcm is imported before or after jax. This matters in practice: test suites, notebooks, and other libraries routinely import jax first, and a cache that is switched off reports nothing at all — it simply recompiles, which on a large model costs minutes per process.

To confirm caching is live in a given process:

import jax

import lcm

print(jax.config.jax_compilation_cache_dir)  # a path
print(jax.config.jax_persistent_cache_min_compile_time_secs)  # 0.0

A directory of None means the cache is off and every fresh process is recompiling the whole model.

On HPC systems where the home directory is on a slow network filesystem, you may want to point the compilation cache at a fast local disk. Set the environment variable before importing pylcm:

import os

os.environ["JAX_COMPILATION_CACHE_DIR"] = os.path.expandvars(
    "/scratch/$USER/.cache/jax"
)

import lcm

Troubleshooting

pylcm
Getting Started
pylcm
A Tiny Example