Metadata-Version: 2.4
Name: PyECLOUD
Version: 8.8.1
Summary: Electron cloud simulations for particle accelerators
License-Expression: Apache-2.0
Project-URL: Source Code, https://github.com/PyCOMPLETE/PyECLOUD
Project-URL: Documentation, https://github.com/PyCOMPLETE/PyECLOUD/wiki
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: pypic-poisson>=2.5.0
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Provides-Extra: pyheadtail
Requires-Dist: PyHEADTAIL; extra == "pyheadtail"
Requires-Dist: h5py; extra == "pyheadtail"
Provides-Extra: hdf5
Requires-Dist: h5py; extra == "hdf5"
Dynamic: license-file

# PyECLOUD

PyECLOUD is a 2D macro-particle code for the simulation of electron cloud effects in particle accelerators.

## Installation

Python 3.11 or newer and working C and Fortran compilers are required. In a conda
environment, these can be installed with `conda install -c conda-forge c-compiler
fortran-compiler`. Activate the environment before building.

```sh
python -m pip install pyecloud
```

Pip automatically installs the Poisson solvers from **pypic-poisson**. Only source
distributions are published for these two packages, so pip builds their native
extensions locally. Their Python import names remain `PyECLOUD` and `PyPIC`.

### Development installation

With sibling PyPIC and PyECLOUD checkouts, run from their parent directory:

```sh
python -m pip install -e ./PyPIC
python -m pip install -e ./PyECLOUD
```

Or, after installing PyPIC, run `python -m pip install -e .` inside this checkout.
Pip installs the Python build dependencies and compiles seven Fortran extensions
with F2PY/Meson and two Cython/C extensions. There is no separate `make` or
`cythonize` step. Cython, Meson, and Ninja are build dependencies; NumPy, SciPy,
matplotlib, and pypic-poisson are runtime dependencies. The unrelated `pypic`
distribution on PyPI is not a dependency. If you previously installed this
PyPIC checkout under the old distribution name `PyPIC`, uninstall it before
reinstalling the renamed package to avoid overlapping installed files.

Python edits take effect immediately with an editable installation. Rerun the
installation command after changing native sources. Use `python -m pip install .`
for a regular installation. `make`, `setup_pyecloud`, and `cythonize` remain
convenience wrappers around the same editable pip installation.

Optional integrations can be installed with `.[pyheadtail]` (PyHEADTAIL and h5py)
or `.[hdf5]` (h5py). PyKLU is optional; the SciPy sparse solver is available with
the core dependencies.

## Running simulations

The Python namespace is unchanged:

```python
from PyECLOUD.buildup_simulation import BuildupSimulation

sim = BuildupSimulation(pyecl_input_folder="/path/to/input_folder")
sim.run()
```

The input folder contains `simulation_parameters.input`, machine and secondary
emission parameters, and beam files. Existing configuration/data paths retain
their original meaning; choose your working directory and output paths as before.

The launch scripts now live under `examples/`:

```sh
python examples/000_run_simulation.py /path/to/input_folder
python examples/001_reload_state_and_run.py /path/to/input_folder /path/to/simulation_state_0.pkl
```

## Repository layout and validation

- `PyECLOUD/`: Python modules, Cython/C sources, and `fortran/` sources.
- `tests/`: automated installation and numerical smoke tests.
- `testing/`: existing simulation regression cases and their reference data.
- `examples/`: simulation launch scripts.
- `other/`, `doc/`, and `dev/`: studies, documentation, and maintenance scripts.

```sh
python -m pip install -e '.[tests]'
python -m pytest
python -m pip install build
python -m build
```

The tests exercise the installed extensions and a short build-up simulation.
`python -m build` creates a source distribution and builds a wheel from it.
The large historical regression datasets stay in the repository and are not
included in the installed package. Version metadata lives in `PyECLOUD/_version.py`;
simulation logs include Git provenance when running from a checkout and work
without Git in a wheel installation.

## Publishing a source release

Publish the required `pypic-poisson` release first. Use a development environment
with the build dependencies installed. Set a new version in `PyECLOUD/_version.py`,
then build and check the source archive:

```sh
python -m pip install build twine
python -m build --sdist
python -m twine check --strict dist/*.tar.gz
```

After testing the archive, commit and push the release changes, then run from
the repository root:

```sh
./release.sh
```

As in xwakes, the script creates and pushes `v<version>` to `origin`, builds an
sdist with `setup.py`, then uploads it using Twine and your PyPI credentials
(for example, configured in `~/.pypirc`). The archive is built in a temporary
directory so only this release's source archive is uploaded, then cleaned up.
No wheels are uploaded. If building or uploading fails after the tag is pushed,
finish the remaining release steps manually.

More information about installation and usage can be found in the [Wiki](https://github.com/PyCOMPLETE/PyECLOUD/wiki).
