λPIC

https://github.com/xsgeng/lambdapic
Admin
λPIC is a callback-centric Particle-In-Cell (PIC) framework that enables customization of simulation...
Tokens:18,455
Snippets:68
Trust Score:5.7
License:GPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Run 2D Laser-Target Example

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/installation.rst

This command executes a sample simulation provided with the λPIC project, demonstrating basic functionality. It requires the lambdapic package to be installed.

```bash
python example/laser-target.py
```

--------------------------------

### Install λPIC from Source

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/installation.rst

This method is for developers or users needing custom builds. It involves cloning the repository and installing the package locally.

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

--------------------------------

### Run λPIC Example with Slurm and MPI

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/installation.rst

This snippet demonstrates how to run the laser-target example using Slurm for job scheduling and MPI for parallel execution. It assumes a system with NUMA nodes configured.

```bash
# 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
```

--------------------------------

### Install λPIC from PyPI

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/installation.rst

This is the recommended installation method for most users, using pip to install the lambdapic package directly from the Python Package Index.

```bash
pip install lambdapic
```

--------------------------------

### Install Prebuilt Conda Packages for λPIC

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/installation.rst

This snippet shows how to create and activate a Conda environment with necessary packages like mpi4py and h5py for λPIC. It's recommended for easier dependency management.

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

--------------------------------

### Simulate QED Photons with Python

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/example.rst

This Python script demonstrates the simulation of QED photons and how to control the on/off state of QED effects during a simulation using a callback. It features an `enable_radiation` switch.

```python
import numpy as np

class SimulationState:
    def __init__(self):
        self.qed_enabled = False
        self.current_time = 0.0

def enable_radiation_callback(state, time_to_enable):
    """Callback function to enable QED radiation at a specific time."""
    if state.current_time >= time_to_enable and not state.qed_enabled:
        state.qed_enabled = True
        print(f"QED radiation enabled at time {state.current_time}")

def run_simulation(duration, time_step, time_to_enable_qed):
    state = SimulationState()
    num_steps = int(duration / time_step)

    for i in range(num_steps):
        state.current_time = i * time_step
        enable_radiation_callback(state, time_to_enable_qed)

        # --- Simulation step --- 
        # In a real simulation, you would update particle and field data here.
        # If state.qed_enabled is True, you would include QED processes.
        if state.qed_enabled:
            # Simulate QED photon emission (e.g., pair production, synchrotron radiation)
            pass
        else:
            # Simulate standard plasma physics without QED effects
            pass
        # --- End Simulation step ---

        # Example: Print status periodically
        if i % (num_steps // 10) == 0:
            print(f"Time: {state.current_time:.2e} s, QED Enabled: {state.qed_enabled}")

    print(f"Simulation finished at time {state.current_time:.2e} s")

if __name__ == '__main__':
    simulation_duration = 1e-12  # seconds
    simulation_time_step = 1e-15 # seconds
    qed_enable_time = 0.5e-12    # seconds

    print("Starting QED photons simulation...")
    run_simulation(simulation_duration, simulation_time_step, qed_enable_time)

```

--------------------------------

### Example AI Prompts for LambdaPic Simulation Configuration

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/AI_prompt.rst

These markdown code blocks demonstrate example prompts to be used with an AI chatbot for configuring LambdaPic simulations. They cover specifying simulation parameters, laser properties, plasma density, and diagnostics.

```markdown
Create a λpic simulation with:
- 2D laser-plasma interaction
- 1024x1024 grid
- Gaussian laser (a0=5, w0=2μm)
- Plasma density 10nc
- Field diagnostics every 100 steps
```

```markdown
Convert this WarpX/EPOCH input to λpic:
[paste input file]
```

```markdown
Fix this error:
[paste error message]
```

--------------------------------

### Simulate Laser Wakefield Acceleration with Python

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/example.rst

This Python script demonstrates the concept of a moving window in laser wakefield acceleration simulations. It provides a basic structure for setting up and potentially visualizing such simulations.

```python
import numpy as np

# Placeholder for simulation parameters and functions
class Simulation:
    def __init__(self, width, height, grid_spacing, time_step):
        self.width = width
        self.height = height
        self.grid_spacing = grid_spacing
        self.time_step = time_step
        self.window_position = 0

    def update(self):
        # Simulate physics and update fields
        # Move the window for moving window simulations
        self.window_position += self.width * self.grid_spacing
        print(f"Window moved to position: {self.window_position}")
        # In a real simulation, you would update EM fields, particle positions, etc.
        pass

    def run_simulation(self, num_steps):
        for step in range(num_steps):
            self.update()
            # Potentially save data or visualize periodically

if __name__ == '__main__':
    # Example parameters for a LWFA simulation with a moving window
    sim_width = 100  # Number of grid points in x
    sim_height = 100 # Number of grid points in y
    dx = 1e-6      # Grid spacing in meters
    dt = 1e-15     # Time step in seconds

    lwfa_sim = Simulation(sim_width, sim_height, dx, dt)
    num_simulation_steps = 50
    lwfa_sim.run_simulation(num_simulation_steps)

```

--------------------------------

### Laser-Wakefield Acceleration Simulation Setup (Python)

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Provides a complete example of setting up a Laser-Wakefield Acceleration (LWFA) simulation using LambdaPic. It defines physical parameters, grid properties, plasma density profile, and initializes the `Simulation` object with relevant settings like time step, CFL condition, and random seed.

```python
import numpy as np
from scipy.constants import c, e, epsilon_0, m_e, mu_0, pi
from lambdapic import *

# Physical parameters
um = 1e-6
l0 = 0.8 * um
omega0 = 2*pi*c/l0
nc = epsilon_0 * m_e * omega0**2 / e**2

# Simulation domain
nx, ny = 1000, 400
dx = dy = l0/20
Lx, Ly = nx*dx, ny*dy

# Plasma profile
def plasma_density(x, y):
    ne = 0.01 * nc
    if x < 5*um or x > 100*um:
        ne = 0
    if abs(y - Ly/2) > Ly/2 - 5*um:
        ne = 0
    return ne

# Create simulation
sim = Simulation(
    nx=nx, ny=ny, dx=dx, dy=dy,
    npatch_x=20, npatch_y=10,
    sim_time=200e-15,
    dt_cfl=0.98,
    random_seed=12345
)
```

--------------------------------

### Simulate Laser Target Interaction with Python

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/example.rst

This Python script simulates a Gaussian laser pulse interacting with a target. It includes functionality to automatically plot simulation data using a callback function.

```python
import numpy as np

import matplotlib.pyplot as plt
from matplotlib.animation import FuncAnimation

def plot_results(data, interval=50):
    fig, ax = plt.subplots()
    im = ax.imshow(data[0], cmap='viridis', origin='lower', aspect='equal', vmin=-1, vmax=1)
    ax.set_title('Laser Target Simulation')
    ax.set_xlabel('X position')
    ax.set_ylabel('Y position')
    plt.colorbar(im, label='Field strength')

    def update(frame):
        im.set_array(data[frame])
        ax.set_title(f'Laser Target Simulation - Frame {frame}')
        return im,

    ani = FuncAnimation(fig, update, frames=len(data), interval=interval, blit=True)
    plt.show()

if __name__ == '__main__':
    # Example simulation data (replace with actual simulation output)
    num_frames = 10
    x_dim, y_dim = 100, 100
    simulation_data = []
    for i in range(num_frames):
        # Create dummy data that changes over time
        frame_data = np.random.rand(x_dim, y_dim) * 2 - 1
        center_x, center_y = x_dim // 2, y_dim // 2
        radius = 10
        y, x = np.ogrid[:x_dim, :y_dim]
        dist_from_center = np.sqrt((x - center_x)**2 + (y - center_y)**2)
        mask = dist_from_center < radius
        frame_data[mask] = np.sin(i * np.pi / num_frames) * (1 - dist_from_center[mask] / radius)
        simulation_data.append(frame_data)

    plot_results(simulation_data)

```

--------------------------------

### Basic 2D Simulation Setup in Python

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/AI_prompt.md

Sets up a basic 2D particle-in-cell simulation using the lambdapic library. It initializes the simulation grid, adds an electron species with a uniform density, and configures field saving callbacks.

```python
from lambdapic import Simulation, Electron, SaveFieldsToHDF5

# Initialize simulation
sim = Simulation(
    nx=512, ny=512, 
    dx=0.8e-6/20, dy=0.8e-6/20,
    npatch_x=8, npatch_y=8
)

# Add species
electron = Electron(
    density=lambda x,y: 1e18,  # 1e18 cm^-3 uniform plasma
    ppc=8
)
sim.add_species(electron)

# Run with diagnostics
sim.run(1000, callbacks=[
    SaveFieldsToHDF5('fields', interval=50)
])
```

--------------------------------

### Use λPIC Auto-reload CLI

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/installation.rst

This shows how to use the λPIC command-line interface with the autoreload feature within a Slurm job script. This allows for modification and re-execution of simulation scripts without requeuing the job.

```bash
# 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
```

--------------------------------

### Define 'Hello World' Callback on Simulation Start

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/write_callbacks.rst

This snippet demonstrates defining a simple callback function using the `@callback` decorator. The function is set to execute at the beginning of the simulation (itime == 0) and prints a 'Simulation started!' message. It requires the `Simulation` object and the `@callback` decorator.

```python
@callback('start', interval=lambda sim: sim.itime == 0)
def hello(sim: Simulation):
    print("Simulation started!")
sim = Simulation(...)
...
sim.run(100, callbacks=[hello])
```

--------------------------------

### Create a 3D Simulation with Callbacks

Source: https://context7.com/xsgeng/lambdapic/llms.txt

This Python code illustrates the setup and execution of a 3D Particle-In-Cell simulation using λPIC. It configures the 3D grid, defines a spatial density profile, and initializes species and callbacks for laser injection.

```python
from lambdapic import Simulation3D, GaussianLaser3D

# 3D grid configuration
nx, ny, nz = 400, 200, 200
dx = dy = dz = l0 / 15

# 3D density profile
def density_3d(x, y, z):
    ne = 0.0
    if x > 2*um:
        r = np.sqrt((y - Ly/2)**2 + (z - Lz/2)**2)
        if r < 5*um:
            ne = 0.02 * nc
    return ne

# Create 3D simulation
sim3d = Simulation3D(
    nx=nx, ny=ny, nz=nz,
    dx=dx, dy=dy, dz=dz,
    npatch_x=8, npatch_y=4, npatch_z=4,
    sim_time=50e-15,
    boundary_conditions={'xmin': 'pml', 'xmax': 'pml',
                         'ymin': 'pml', 'ymax': 'pml',
                         'zmin': 'pml', 'zmax': 'pml'}
)

# Add species and run
electron_3d = Electron(density=density_3d, ppc=4)
sim3d.add_species([electron_3d])
sim3d.initialize()

sim3d.run(callbacks=[
    GaussianLaser3D(a0=5, l0=0.8e-6, w0=3e-6, ctau=10e-6,
                    focus_position=10e-6, pol_angle=0),
])

```

--------------------------------

### Full Simulation Example: Laser Incident on Carbon Target in Python

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/AI_prompt.md

Sets up and runs a full particle-in-cell simulation involving a laser incident on a carbon target. It defines simulation parameters, species (Electron, Proton, Carbon), initializes a Gaussian laser, and sets up callbacks for plotting and saving data. Requires lambdapic library, matplotlib, and pathlib.

```python
from pathlib import Path

import matplotlib.pyplot as plt
from matplotlib.colors import LinearSegmentedColormap

from lambdapic import (
    Electron,
    GaussianLaser2D,
    Proton,
    SaveFieldsToHDF5,
    SaveSpeciesDensityToHDF5,
    Simulation,
    Species,
    c,
    callback,
    e,
    epsilon_0,
    get_fields,
    m_e,
    pi,
)

um = 1e-6
l0 = 0.8 * um
t0 = l0 / c
omega0 = 2 * pi * c / l0
nc = epsilon_0 * m_e * omega0**2 / e**2

nx = 1024
ny = 1024
dx = l0 / 50
dy = l0 / 50

Lx = nx * dx
Ly = ny * dy


def density(n0):
    def _density(x, y):
        ne = 0.0
        if x > Lx/2 and x < Lx/2+1*um:
            ne = n0
        return ne
    return _density

laser = GaussianLaser2D(
    a0=10,
    w0=2e-6,
    l0=0.8e-6,
    ctau=5e-6,
    focus_position=Lx/2,
)

if __name__ == "__main__":
    sim = Simulation(
        nx=nx,
        ny=ny,
        dx=dx,
        dy=dy,
        npatch_x=16,
        npatch_y=16,
    )

    ele = Electron(density=density(10*nc), ppc=10)
    proton = Proton(density=density(10*nc/8*2), ppc=10)
    carbon = Species(name="C", charge=6, mass=12*1800, density=density(10*nc/8), ppc=10)

    sim.add_species([ele, carbon, proton])

    @callback(interval=100)
    def plot_results(sim: Simulation):
        it = sim.itime
        ex, ey, ez, bx, by, bz, jy, rho = get_fields(sim, ['ex', 'ey', 'ez', 'bx', 'by', 'bz', 'jy', 'rho'])
        
        if sim.mpi.rank > 0:
            return
        ey *= e / (m_e * c * omega0)

        bwr_alpha = LinearSegmentedColormap(
            'bwr_alpha',
            dict( 
                red=[ (0, 0, 0), (0.5, 1, 1), (1, 1, 1) ], 
                green=[ (0, 0.5, 0), (0.5, 1, 1), (1, 0, 0) ], 
                blue=[ (0, 1, 1), (0.5, 1, 1), (1, 0, 0) ], 
                alpha = [ (0, 1, 1), (0.5, 0, 0), (1, 1, 1) ]
            )
        )
        fig, ax = plt.subplots(figsize=(5, 3), layout="constrained")

        h1 = ax.imshow(
            -rho.T/e/nc, 
            extent=[0, Lx, 0, Ly],
            origin='lower',
            cmap='Grays',
            vmax=20,
            vmin=0,
        )
        h2 = ax.imshow(
            ey.T, 
            extent=[0, Lx, 0, Ly],
            origin='lower',
            cmap=bwr_alpha,
            vmax=laser.a0,
            vmin=-laser.a0,
        )
        fig.colorbar(h1)
        fig.colorbar(h2)

        figdir = Path('laser-target')
        if not figdir.exists():
            figdir.mkdir()

        fig.savefig(figdir/f'{it:04d}.png', dpi=300)
        plt.close()

    
    sim.run(2001, callbacks=[
            laser, 
            plot_results,
            SaveFieldsToHDF5('laser-target/fields', 100, ['ex', 'ey', 'ez', 'bx', 'by', 'bz', 'rho']),
            SaveSpeciesDensityToHDF5(carbon, 'laser-target/density', 100),
            SaveSpeciesDensityToHDF5(ele, 'laser-target/density', 100),
        ]
    )
```

--------------------------------

### Set Thread Count for Performance

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/installation.rst

These environment variables, OMP_NUM_THREADS and NUMBA_NUM_THREADS, are used to control the number of threads for parallel execution, optimizing performance on multi-core systems.

```bash
export OMP_NUM_THREADS=24
export NUMBA_NUM_THREADS=24
```

--------------------------------

### Configure Constant Velocity Moving Window (Python)

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Sets up a constant velocity moving window for laser-plasma interactions. It specifies the window's velocity (e.g., speed of light), when it should start, whether to inject particles, and when to stop injection. Requires the `MovingWindow` class from `lambdapic`.

```python
from lambdapic import MovingWindow

# Constant velocity moving window
moving_window = MovingWindow(
    velocity=c,  # Speed of light
    start_time=Lx/c,  # Start after light crosses domain
    inject_particles=True,  # Inject new particles at boundary
    stop_inject_time=100e-15  # Stop injection after 100 fs
)
```

--------------------------------

### Implement Custom Callbacks using Decorators

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Shows how to define custom callbacks for diagnostics using Python decorators. This example defines an energy diagnostic function that calculates and logs the total field energy at specific simulation stages and intervals. Requires `lambdapic` and assumes `epsilon_0`, `mu_0` are defined.

```python
from lambdapic import callback, Simulation

# Function-based callback with decorator
@callback(stage='maxwell second', interval=100)
def energy_diagnostic(sim):
    """Calculate and log total field energy"""
    energy = 0
    for p in sim.patches:
        e2 = (p.fields.ex**2 + p.fields.ey**2 + p.fields.ez**2).sum()
        b2 = (p.fields.bx**2 + p.fields.by**2 + p.fields.bz**2).sum()
        energy += (epsilon_0*e2 + b2/mu_0) * p.dx * p.dy # Assuming epsilon_0 and mu_0 are defined

    total_energy = sim.mpi.comm.reduce(energy, root=0)
    if sim.mpi.rank == 0:
        print(f"t={sim.time:.2e} s, E_field={total_energy:.2e} J")
```

--------------------------------

### Calculate and Sum Total EM Energy

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/write_callbacks.rst

This snippet defines a callback to calculate the total electromagnetic energy within the simulation domain. It iterates through all patches, sums the energy contributions from electric and magnetic fields, and then uses MPI reduction to get the global sum. The result is printed only on the root process. It's designed to run at specified intervals (e.g., every 100 iterations). Dependencies include `Simulation`, `numpy`, `epsilon_0`, and `mu_0`.

```python
sim = Simulation(...)
ele = Electron(name='ele', ppc=10, density=...)
...

@callback('start', interval=100)
def sum_EM_enerty(sim: Simulation):
    Eem = 0.0
    # sum over all patches
    for p in sim.patches:
        f = p.fields
        # NOTE: guard cells are in the [nx_per_patch:, ny_per_patch:] region
        s = np.s_[:sim.nx_per_patch, :sim.ny_per_patch]
        Eem += (0.5*epsilon_0*(f.ex[s]**2+f.ey[s]**2+f.ez[s]**2) + 
                0.5/mu_0     *(f.bx[s]**2+f.by[s]**2+f.bz[s]**2)).sum()

    # sum over all mpi ranks
    Eem = sim.mpi.comm.reduce(Eem)
    if sim.mpi.rank > 0:
        return
    
    # print, or save to some file
    print(f"{Eem=:g}")
```

--------------------------------

### Accessing Live Particles with NumPy

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/core/particles.rst

Demonstrates how to filter and operate on live particles using the 'is_alive' boolean mask. This is useful for calculations and updates that should only apply to active particles. It shows examples of incrementing particle properties and performing histogram operations.

```python
particles.ux[particles.is_alive] += 10
np.histogram(particles.ux[particles.is_alive], weights=particles.w[particles.is_alive])
```

--------------------------------

### Simulation Initialization

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/AI_prompt.md

Provides details on how to initialize a 2D PIC simulation using the `Simulation` class.

```APIDOC
## POST /api/simulation/initialize

### Description
Initializes a 2D Particle-In-Cell (PIC) simulation.

### Method
POST

### Endpoint
/api/simulation/initialize

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **nx** (integer) - Required - Number of cells in x direction
- **ny** (integer) - Required - Number of cells in y direction
- **dx** (float) - Required - Cell size in x direction (meters)
- **dy** (float) - Required - Cell size in y direction (meters)
- **npatch_x** (integer) - Required - Number of patches in x direction
- **npatch_y** (integer) - Required - Number of patches in y direction
- **dt_cfl** (float) - Optional - CFL condition factor (default: 0.95)
- **n_guard** (integer) - Optional - Number of guard cells (default: 3)
- **cpml_thickness** (integer) - Optional - CPML boundary thickness in cells (default: 6)
- **log_file** (string) - Optional - Log file name (default: auto-generated based on timestamp)
- **truncate_log** (boolean) - Optional - Whether to truncate existing log file (default: True)

### Request Example
```json
{
  "nx": 512,
  "ny": 512,
  "dx": 0.8e-6/20,
  "dy": 0.8e-6/20,
  "npatch_x": 8,
  "npatch_y": 8,
  "dt_cfl": 0.95
}
```

### Response
#### Success Response (200)
- **simulation_id** (string) - Unique identifier for the simulation instance

#### Response Example
```json
{
  "simulation_id": "sim_abc123"
}
```
```

--------------------------------

### Initialize and Run λPIC Simulation with Callbacks

Source: https://context7.com/xsgeng/lambdapic/llms.txt

This snippet initializes the λPIC simulation and runs it with a predefined list of callbacks. These callbacks include the laser, moving window, density diagnostic, field plotting, the custom energy diagnostic, and saving field and particle data to HDF5 files. Dependencies include the 'lambdapic' library and its associated diagnostic and output classes.

```python
# Initialize and run
sim.initialize()
sim.run(callbacks=[
    laser, window, ne, plot, energy_diagnostic,
    SaveFieldsToHDF5('output/fields', interval=20e-15,
                     components=['ey', 'bz', 'rho']),
    SaveParticlesToHDF5(electron, 'output/electrons',
                        interval=20e-15,
                        attrs=['x', 'y', 'ux', 'uy', 'w'])
])
```

--------------------------------

### Simulation Execution

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/AI_prompt.md

APIs related to running and managing the simulation steps and callbacks.

```APIDOC
## POST /api/simulation/run

### Description
Executes the PIC simulation for a specified number of steps with optional callbacks.

### Method
POST

### Endpoint
/api/simulation/run

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **simulation_id** (string) - Required - The ID of the simulation instance to run
- **num_steps** (integer) - Required - The number of simulation steps to perform
- **callbacks** (array) - Optional - A list of callbacks to execute during the simulation
  - Each callback object can have:
    - **type** (string) - Required - Type of callback (e.g., 'SaveFieldsToHDF5', 'CustomFunction')
    - **config** (object) - Optional - Configuration for the callback (e.g., filename, interval for 'SaveFieldsToHDF5')
    - **function_code** (string) - Optional - JavaScript or Python code for a custom function callback

### Request Example
```json
{
  "simulation_id": "sim_abc123",
  "num_steps": 1000,
  "callbacks": [
    {
      "type": "SaveFieldsToHDF5",
      "config": {
        "filename": "fields",
        "interval": 50
      }
    },
    {
      "type": "CustomFunction",
      "function_code": "function add_fields(sim) {\n  for (let p of sim.patches) {\n    p.fields.bz += 10.0; // Add 10T Bz field\n  }\n}"
    }
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the simulation run completed successfully.

#### Response Example
```json
{
  "status": "Simulation run completed."
}
```
```

--------------------------------

### Configure Simple 2D and 3D Lasers

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Sets up simple 2D and 3D lasers with Gaussian transverse profiles. Demonstrates configurations for linear and circular polarization, different beam waists, wavelengths, pulse durations, and injection sides. Requires `lambdapic` and `scipy.constants`.

```python
from lambdapic import SimpleLaser2D, SimpleLaser3D
from scipy.constants import c, pi

# 2D simple laser (Gaussian transverse profile)
laser_2d = SimpleLaser2D(
    a0=2.0,  # Normalized vector potential
    w0=5e-6,  # Beam waist (5 μm)
    l0=0.8e-6,  # 800 nm wavelength
    ctau=10e-6,  # Pulse duration (10 μm = 33 fs)
    pol_angle=0.0,  # Linear polarization in z
    side='xmin'  # Inject from left boundary
)

# Circularly polarized laser
laser_circular = SimpleLaser2D(
    a0=3.0,
    w0=4e-6,
    l0=1.0e-6,
    ctau=5e-6,
    pol_angle=pi/4  # 45-degree polarization
)

# 3D simple laser
laser_3d = SimpleLaser3D(
    a0=5.0,
    w0=3e-6,
    l0=0.8e-6,
    ctau=15e-6
)
```

--------------------------------

### Extract Field Data to Rank 0 (Python)

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Extracts specific field data (e.g., 'ex', 'ey', 'bz') from all MPI ranks to the root rank (rank 0). The `get_fields` function returns a tuple of field arrays on rank 0 and None on other ranks. The extracted data can then be processed or visualized, for example, using Matplotlib.

```python
from lambdapic import get_fields

# Extract fields to rank 0 (returns None on other ranks)
fields = get_fields(sim, ['ex', 'ey', 'bz'])
if sim.mpi.rank == 0:
    ex, ey, bz = fields
    # Process on rank 0
    import matplotlib.pyplot as plt
    plt.imshow(ey.T, origin='lower', cmap='bwr')
    plt.savefig('field_snapshot.png')
```

--------------------------------

### Create and Run a 2D Simulation with Callbacks

Source: https://context7.com/xsgeng/lambdapic/llms.txt

This Python code demonstrates how to set up and run a 2D Particle-In-Cell simulation using the λPIC framework. It defines physical and grid parameters, species, boundary conditions, and employs callbacks for laser initialization, moving window, and data saving.

```python
import numpy as np
from scipy.constants import c, e, epsilon_0, m_e, pi
from lambdapic import (
    Simulation, Electron, Proton, Species,
    SimpleLaser2D, MovingWindow, SaveFieldsToHDF5,
    PlotFields, ExtractSpeciesDensity
)

# Physical parameters
um = 1e-6
l0 = 0.8 * um  # 800nm laser
omega0 = 2 * pi * c / l0
nc = epsilon_0 * m_e * omega0**2 / e**2  # Critical density

# Grid configuration
nx, ny = 500, 800
dx = dy = l0 / 20  # 20 points per wavelength
Lx = nx * dx
Ly = ny * dy

# Density profile function
def density(n0):
    def _density(x, y):
        ne = 0.0
        if x > 1*um:
            ne = n0
        if abs(y - Ly/2) > Ly/2 - 1*um:
            ne = 0
        return ne
    return _density

# Create simulation with automatic patch decomposition
sim = Simulation(
    nx=nx, ny=ny,
    dx=dx, dy=dy,
    npatch_x=10, npatch_y=10,  # Domain decomposition
    dt_cfl=0.99,
    sim_time=100e-15,  # 100 fs simulation
    boundary_conditions={'xmin': 'pml', 'xmax': 'pml',
                         'ymin': 'pml', 'ymax': 'pml'},
    cpml_thickness=6,
    random_seed=42  # For reproducibility
)

# Define particle species
ne = 0.01 * nc
electron = Electron(density=density(ne), ppc=10, name='electron')
proton = Proton(density=density(ne/8*2), ppc=2, name='ion')
carbon = Species(name="C6+", charge=6, mass=12*1800,
                 density=density(ne/8), ppc=1)

# Add species to simulation
sim.add_species([electron, carbon, proton])

# Initialize and run (must call before run)
sim.initialize()

# Run simulation with callbacks
sim.run(callbacks=[
    SimpleLaser2D(a0=2, w0=5e-6, l0=0.8e-6, ctau=5e-6),
    MovingWindow(velocity=c, start_time=Lx/c),
    SaveFieldsToHDF5('output/fields', interval=100,
                     components=['ex', 'ey', 'bz'])
])

```

--------------------------------

### Load Initial Particles from HDF5 (Python)

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Loads initial particle distributions from an HDF5 file at the beginning of the simulation. The `LoadParticles` class requires the species, file path, and an interval condition (typically `sim.itime == 0`). The HDF5 file must contain datasets for position ('/x', '/y', '/z') and weight ('/w'), with optional momentum and ID datasets.

```python
from lambdapic import LoadParticles

# Load particles at initialization
load_particles = LoadParticles(
    species=electron,
    file='initial_particles.h5',
    interval=lambda sim: sim.itime == 0
)
```

--------------------------------

### Moving Window Technique in Python

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/AI_prompt.md

Implements the moving window technique along the x-direction, allowing the simulation domain to shift periodically. This is useful for tracking phenomena like laser or plasma flow while maintaining proper boundary conditions.

```python
class MovingWindow:
    """Callback implementing moving window technique along x-direction.

    The moving window follows the laser or plasma flow by periodically shifting
    the simulation domain while maintaining proper boundary conditions.

    Args:
        velocity (Union[float, Callable[[float], float]]): Window velocity in m/s. 
            Can be constant or function of time (velocity=f(sim.time))
    """
    pass
```

--------------------------------

### Configure Moving Window and Diagnostics in λPIC

Source: https://context7.com/xsgeng/lambdapic/llms.txt

This section configures a moving window for the simulation, allowing the window to move with the simulation's velocity. It also sets up diagnostics to extract species density and plot electromagnetic fields, specifying the fields to plot, their scaling, colormaps, and intervals for data collection. Dependencies include the 'lambdapic' library and specified units.

```python
# Moving window
window = MovingWindow(velocity=c, start_time=50e-15)

# Diagnostics
ne = ExtractSpeciesDensity(sim, electron, interval=10e-15)
plot = PlotFields(
    [
        dict(field=ne.density, scale=1/nc, cmap='Grays',
             vmin=0, vmax=0.03),
        dict(field='ey', scale=e/(m_e*c*omega0),
             cmap='bwr_alpha', vmin=-4, vmax=4)
    ],
    prefix='lwfa',
    interval=10e-15
)
```

--------------------------------

### Simulation Class Initialization in Python

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/AI_prompt.md

Details the initialization parameters for the `Simulation` class in lambdapic. This class is central to setting up 2D Particle-In-Cell simulations, defining grid dimensions, cell sizes, and parallel decomposition.

```python
class Simulation:
"""Main simulation class for 2D Particle-In-Cell (PIC) simulations."""
def __init__(
    self,
    nx: int,
    ny: int,
    dx: float,
    dy: float,
    npatch_x: int,
    npatch_y: int,
    dt_cfl: float = 0.95,
    n_guard: int = 3,
    cpml_thickness: int = 6,
    log_file: Optional[str] = None,
    truncate_log: bool = True
) -> None:
    """Initialize a 2D PIC simulation.

    Args:
        nx: Number of cells in x direction
        ny: Number of cells in y direction
        dx: Cell size in x direction (meters)
        dy: Cell size in y direction (meters)
        npatch_x: Number of patches in x direction
        npatch_y: Number of patches in y direction
        dt_cfl: CFL condition factor (default: 0.95)
        n_guard: Number of guard cells (default: 3)
        cpml_thickness: CPML boundary thickness in cells (default: 6)
        log_file: Log file name (default: auto-generated based on timestamp)
        truncate_log: Whether to truncate existing log file (default: True)

```

--------------------------------

### Configure Gaussian Lasers with Beam Physics

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Sets up 2D and 3D Gaussian lasers that include effects like Rayleigh length, Gouy phase, and wavefront curvature. Allows specifying focus position, pulse center, polarization, and injection stop time. Requires `lambdapic`.

```python
from lambdapic import GaussianLaser2D, GaussianLaser3D

# Gaussian laser with Rayleigh length, Gouy phase, wavefront curvature
laser_gaussian = GaussianLaser2D(
    a0=4.0,
    l0=0.8e-6,
    w0=4e-6,  # Waist at focus
    ctau=8e-6,
    x0=24e-6,  # Pulse center position (default: 3*ctau)
    focus_position=50e-6,  # Focus 50 μm from boundary
    pol_angle=0.0,
    tstop=100e-15  # Stop injection at 100 fs
)

# 3D Gaussian laser focused inside target
laser_3d_focused = GaussianLaser3D(
    a0=10.0,
    l0=1.0e-6,
    w0=2e-6,
    ctau=10e-6,
    focus_position=20e-6,  # Focus 20 μm inside domain
    pol_angle=pi/2  # Perpendicular polarization
)

# Rayleigh length automatically calculated
print(f"Rayleigh length: {laser_gaussian.zR:.2e} m")
```

--------------------------------

### Common Operations in Python (Laser, Field Modification)

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/AI_prompt.md

Demonstrates common operations within the lambdapic simulation framework. This includes initializing a Gaussian laser pulse and a custom callback function to modify simulation fields.

```python
# Laser initialization
from lambdapic import GaussianLaser2D
laser = GaussianLaser2D(
    a0=5, w0=5e-6, focus_position=20e-6
)

# Custom field modification
@callback('interpolator')
def add_fields(sim):
    for p in sim.patches:
        p.fields.bz[:] += 10.0  # Add 10T Bz field
```

--------------------------------

### Configure QED-enabled Particles and Pair Production

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Sets up QED-enabled electron with photon emission and configures pair production involving a positron. Also demonstrates defining a custom ion species (Carbon) and a spatially varying particle-per-cell (PPC) distribution for electrons.

```python
from lambdapic import Photon, Electron, Positron, Species

# QED-enabled electron (with photon emission)
photon = Photon(name='gamma')
electron_qed = Electron(
    name='e_qed',
    density=lambda x, y: 1e26,
    ppc=15,
    radiation='photons'  # Enable photon emission
)
electron_qed.set_photon(photon)

# Pair production setup
positron = Positron(name='positron', density=None, ppc=0)
photon_pp = Photon(name='gamma_pp')
photon_pp.set_bw_pair(electron=electron_qed, positron=positron)

# Custom ion species
carbon_ion = Species(
    name='C6+',
    charge=6,  # Ionization state
    mass=12 * 1836,  # Mass in electron masses
    density=lambda x, y: 1e24,
    ppc=2
)

# Spatially varying PPC
def ppc_adaptive(x, y):
    """More particles in high-density regions"""
    if x > 10e-6:
        return 20
    return 5

electron_adaptive = Electron(
    density=lambda x, y: 1e25,
    ppc=ppc_adaptive
)
```

--------------------------------

### Use Built-in Callbacks for Data Output

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Demonstrates using built-in callbacks from `lambdapic` to save simulation data. Includes saving electromagnetic fields and particle attributes to HDF5 with various interval settings (step-based, time-based, conditional). Also shows plotting fields during simulation. Requires `lambdapic` and assumes `sim`, `electron`, `proton`, `nc`, `e`, `m_e`, `c`, `omega0` are defined.

```python
from lambdapic import (
    SaveFieldsToHDF5, SaveParticlesToHDF5,
    SaveSpeciesDensityToHDF5, PlotFields, ExtractSpeciesDensity
)

# Save electromagnetic fields to HDF5
save_fields = SaveFieldsToHDF5(
    prefix='output/fields',
    interval=100,  # Every 100 steps
    components=['ex', 'ey', 'ez', 'bx', 'by', 'bz', 'jx', 'rho']
)

# Save with time-based interval (every 10 fs)
save_fields_time = SaveFieldsToHDF5(
    prefix='output/fields',
    interval=10e-15,  # Time in seconds
    components=['ey', 'bz']
)

# Save with custom condition
def save_condition(sim):
    """Save only when field exceeds threshold"""
    max_ey = max(p.fields.ey.max() for p in sim.patches)
    return sim.mpi.comm.allreduce(max_ey) > 1e11

save_fields_conditional = SaveFieldsToHDF5(
    prefix='output/fields',
    interval=save_condition
)

# Save particle data
save_particles = SaveParticlesToHDF5(
    species=electron, # Assuming 'electron' is defined
    prefix='output/particles',
    interval=200,
    attrs=['x', 'y', 'ux', 'uy', 'uz', 'w']  # Select attributes
)

# Save species density
save_density = SaveSpeciesDensityToHDF5(
    species=proton, # Assuming 'proton' is defined
    prefix='output/density',
    interval=50
)

# Plot fields during simulation (rank 0 only)
# Assuming 'sim', 'electron', 'nc', 'e', 'm_e', 'c', 'omega0' are defined
ne_ele = ExtractSpeciesDensity(sim, electron, interval=100)
plot = PlotFields(
    [
        dict(field=ne_ele.density, scale=1/nc, cmap='Grays',
             vmin=0, vmax=0.05, label='n_e/n_c'),
        dict(field='ey', scale=e/(m_e*c*omega0), cmap='bwr_alpha',
             vmin=-2, vmax=2, label='E_y/(mcω/e)')
    ],
    prefix='plots/fields',
    interval=100
)
```

--------------------------------

### Simple Laser Pulse Implementation (Python)

Source: https://github.com/xsgeng/lambdapic/blob/main/docs/source/AI_prompt.md

Provides a basic implementation for injecting a laser pulse with a Gaussian transverse profile and a smooth temporal envelope from the left boundary. It is intended for simple simulations and is not recommended for direct use, with SimpleLaser2D or SimpleLaser3D preferred for actual 2D and 3D simulations. It does not account for beam evolution or complex phase effects.

```python
class SimpleLaser(Laser):
    """
    A simple laser pulse implementation with basic spatial and temporal profiles.
    This class provides a straightforward way to inject a laser pulse into the simulation
    from the left boundary with a Gaussian transverse profile and a smooth temporal envelope.

    Use `SimpleLaser2D` or `SimpleLaser3D` for 2D and 3D simulations, respectively.
    DO NOT use this class directly.
    
    Attributes:
        a0 (float): Normalized vector potential amplitude
        l0 (float): Laser wavelength
        omega0 (float): Laser angular frequency (2πc/λ)
        w0 (float): Laser waist size (determines transverse width of the beam)
        ctau (float): Pulse duration (c*tau)
        E0 (float): Peak electric field amplitude, derived from a0
        pol_angle (float): Polarization angle in radians, 0 for z-polarization, π/2 for y-polarization
    
    Note:
        This is a simplified laser implementation suitable for basic simulations.
        For more accurate physics including proper beam evolution, wavefront curvature,
        and Gouy phase, use the GaussianLaser class instead.
    """

```

--------------------------------

### Configure Backward Moving Window (Python)

Source: https://context7.com/xsgeng/lambdapic/llms.txt

Sets up a moving window that travels in the backward direction. This is achieved by providing a negative velocity value to the `MovingWindow` constructor. Particle injection is typically disabled for backward windows. Requires the `MovingWindow` class.

```python
moving_window_back = MovingWindow(
    velocity=-0.5*c,  # Negative for backward
    inject_particles=False
)
```
Tokens:
Raw