WarpX Geometry

Simple geometry objects for WarpX embedded boundaries.

Combine shapes in Python, and warpx-geometry writes the analytic expressions that WarpX needs for the geometry and for the voltage on each conductor, in Cartesian (XYZ) and cylindrical (RZ) coordinates.

Read the documentation for the guides, examples and API reference.

Gallery

An einzel lens followed by a suppressor ring and a Faraday cup, built in RZ (einzel_lens_faraday_cup.py):

The potential of an einzel lens, solved with WarpX (warpx_einzel_lens.py):

"warpX" built from boxes, rotated boxes and hollow cylinders (warpx_letters.py):

Installation

With uv:

uv pip install warpx-geometry
uv pip install "warpx-geometry[viz]"  # for 3D plots

With pip:

pip install warpx-geometry
pip install "warpx-geometry[viz]"  # for 3D plots

Example

from warpx_geometry import CylinderZ_hollow, Geometry

# dimensions in m
lens = CylinderZ_hollow(0.011, 0.009, -0.005, 0.005, name="lens", default_voltage=5000)
tube = CylinderZ_hollow(0.030, 0.028, -0.05, 0.05, name="tube")

geometry = Geometry(lens + tube, rz=True)

eb_function = str(geometry)  # warpx.eb_implicit_function
potential = geometry.to_potential_expr()  # warpx.eb_potential(x,y,z,t)

Using AI assistants

The repository includes a skill that teaches AI assistants how to use the package. See Using AI assistants.

Contributing

Contributions are welcome. See the development guide, and open an issue for questions or problems.

Citation

If you use this package in your research, please cite:

@software{warpx_geometry,
  author = {Persaud, Arun},
  title = {WarpX Geometry: Simple geometry objects for WarpX},
  url = {https://github.com/BLAST-WarpX/warpx-geometry},
  year = {2026}
}

License

WarpX Copyright (c) 2018, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.

If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Innovation & Partnerships Office at IPO@lbl.gov.

Please see the full license agreement in LICENSE.txt. Please see the notices in NOTICE.txt. The SPDX license identifier is BSD-3-Clause-LBNL.