Installation & Usage

System Requirements

  • Python with headers, tested on 3.12

  • GCC >= 9.3 (for building from source)

  • Conda (recommended for dependency management)

Installation

  1. Install prebuilt packages from Conda (recommended)

First install prebuilt packages from conda like mpi4py and h5py which can be difficult to build:

conda create -n lambdapic python==3.12 mpi4py h5py numpy scipy
conda activate lambdapic

  1. Install λPIC

From PyPI (recommended for most users):

pip install lambdapic

From source (for development or custom builds):

git clone https://github.com/xsgeng/lambdapic.git
cd lambdapic
pip install .

Running Examples

See Examples, or use examples from the repo. To run the 2D laser-target example:

python example/laser-target.py

These examples demonstrate basic functionality and can be modified for your own simulations.

You can set number of threads via OMP_NUM_THREADS and NUMBA_NUM_THREADS.

export OMP_NUM_THREADS=24
export NUMBA_NUM_THREADS=24

For MPI run, the number of processes should be equal to the number of NUMA nodes. On Epyc 9004, the number of NUMA nodes is 8 on dual socket nodes.

# Slurm, no need to set num threads
srun -c24 -n8 -u python example/laser-target.py

# MPICH
export OMP_NUM_THREADS=24
export NUMBA_NUM_THREADS=24
mpiexec -np 8 -ppn 8 python -u example/laser-target.py

Auto-reload functionality

You can also run from the λPIC commandline interface (CLI).

Currently, the CLI supports autoreload functionality. The simulation script will be automatically reloaded on modification. This is useful in HPC environments when you want to modify & re-run the simulation without re-queuing the job.

# in a sbatch script
#SBATCH -c24
#SBATCH -n8
#SBATCH -u
...
srun lambdapic autoreload example/laser-target.py

# find somethig wrong in the output figures.
# modify example/laser-target.py ...
# job will automatically restart with new script

Note

You should put the sim.run in the __name__ == "__main__" block to avoid run on import, since the CLI will reload and call run.

Troubleshooting

  • If you encounter build errors, ensure you have GCC 9.3 or newer installed

  • For MPI-related issues, verify mpi4py is working in your conda environment

  • Building from source requires development headers for Python and MPI