Metadata-Version: 2.4
Name: virtual-ipm
Version: 2.3.1
Summary: Virtual-IPM is a software for simulating transverse profile monitors under the influence of beam space-charge and external fields.
Home-page: https://gitlab.com/IPMsim/Virtual-IPM
Author: Dominik Vilsmeier
Author-email: dominik.vilsmeier1123@gmail.com
License: AGPL-3.0
Project-URL: Documentation, https://ipmsim.gitlab.io/Virtual-IPM/
Project-URL: Code, https://gitlab.com/IPMsim/Virtual-IPM
Project-URL: Issue tracker, https://gitlab.com/IPMsim/Virtual-IPM/-/issues
Project-URL: Changelog, https://ipmsim.gitlab.io/Virtual-IPM/changelog.html
Keywords: IPM,BGI,BIF,beam instrumentation,beam diagnostics,transverse profile monitor,simulation,framework,ionization profile monitor,beam gas ionization profile monitor,beam induced fluorescence monitor,space charge,particle accelerator
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE.md
Requires-Dist: anna>=0.5.2
Requires-Dist: injector==0.12.1
Requires-Dist: ionics
Requires-Dist: numpy>=1.18
Requires-Dist: pandas
Requires-Dist: pyhocon
Requires-Dist: rich>=13.8
Requires-Dist: rx<3.0
Requires-Dist: scipy
Requires-Dist: six
Provides-Extra: gui
Requires-Dist: PyQt5; extra == "gui"
Requires-Dist: matplotlib>=3.2; extra == "gui"
Provides-Extra: obstacles
Requires-Dist: trimesh[easy]; extra == "obstacles"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: matplotlib; extra == "tests"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

|PyPI status| |Maintenance yes| |Documentation Status| |PyPI pyversions| |PyPI version| |GPLv3 license|

|
|
|

.. image:: https://gitlab.com/IPMsim/Virtual-IPM/-/raw/develop/logo.svg
   :align: center
   :width: 100%


Virtual-IPM
===========

Virtual-IPM is a software for simulating the electron/ion transport in Ionization Profile Monitors (IPM)
and other related devices, such as Beam Induced Fluorescence Monitors (BIF).
It can simulate quite general setups involving the space-charge fields from one or multiple particle beams
as well as the presence of external electric/magnetic guiding fields.
The application can be used from the command line but it offers a rich graphical user interface (GUI) as well.

The software has a modular structure which allows for great flexibility in terms of combining the various
different realizations of beam fields, external fields, detector geometry, etc.


Use cases
---------

The following list is a brief overview of possible `use cases <https://ipmsim.gitlab.io/Virtual-IPM/use-cases.html>`__:

* Beam profile deformation due to beam space-charge
* Beam profile deformation due to guiding field non-uniformities
* Gas-jet for IPM and BIF
* Simulating the effect of multiple beams on electron/ion transport


Components
----------

The following is an overview of the available implementations for the various modules:

+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
| Bunch shapes | Bunch fields   | External fields | Devices                                 | Particle generation        |
+==============+================+=================+=========================================+============================+
| Uniform      | Uniform        | Uniform         | Ionization Profile Monitor (IPM)        | Ionization via beam (IPM): |
|              |                |                 |                                         |                            |
|              |                |                 |                                         | * at rest                  |
|              |                |                 |                                         | * parametrized DDCS        |
|              |                |                 |                                         | * DDCS by Voitkiv et al.   |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
| Gaussian     | Gaussian       | 2D field maps   | Beam Induced Fluorescence Monitor (BIF) | Excitation via beam (BIF)  |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
| Gaussian DC  | Gaussian DC    | 3D field maps   | Arbitrary CAD models (via .STL files)   | Thermal motion             |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
| Generalized  | Generalized    | Thin Wire       |                                         | Gas jets                   |
| Gaussian     | Gaussian       | electric field  |                                         |                            |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
| QGaussian    | QGaussian      |                 |                                         | Custom CSV files           |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
| Hollow DC    | Hollow DC      |                 |                                         |                            |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
| Parabolic    | Parabolic      |                 |                                         |                            |
| Ellipsoid    | Ellipsoid      |                 |                                         |                            |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
|              | Poisson 2D SOR |                 |                                         |                            |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
|              | Poisson 3D     |                 |                                         |                            |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+


Installation
------------

Virtual-IPM can be installed via ``pip`` with or without GUI components. ``pip install Virtual-IPM[GUI]`` installs
the application together with the graphical user interface while ``pip install Virtual-IPM`` just installs the command
line version. For more information see `the documentation <https://ipmsim.gitlab.io/Virtual-IPM/installation.html>`__.


Graphical User Interface
------------------------

`The GUI <https://ipmsim.gitlab.io/Virtual-IPM/usage.html#via-the-gui>`__
can be started via ``virtual-ipm-gui``. At the top, it offers buttons for various functionality:

* Create, save and load configuration files
* Run configurations
* Analyze simulation output
* `Create parameter sweeps <https://ipmsim.gitlab.io/Virtual-IPM/parameter-sweeps.html>`__


Command Line Usage
------------------

`The application <https://ipmsim.gitlab.io/Virtual-IPM/usage.html#via-the-command-line>`__
can be run from the command line via ``virtual-ipm path/to/config.xml``.
For customization and options see ``virtual-ipm --help``.

The application also ships with a number of other
`command line utilities <https://ipmsim.gitlab.io/Virtual-IPM/usage.html#command-line-tools>`__,
e.g. for plotting beam fields from configuration files.


Contributing
------------

Please contact `the maintainers <https://gitlab.com/IPMsim/Virtual-IPM/-/blob/develop/setup.py#L38>`__.


Relevant links
--------------

* `Documentation <https://ipmsim.gitlab.io/Virtual-IPM/>`__
* `Changelog / Release notes <https://ipmsim.gitlab.io/Virtual-IPM/changelog.html>`__
* `Examples <https://ipmsim.gitlab.io/Virtual-IPM/examples.html>`__
* `Issue tracker <https://gitlab.com/IPMsim/Virtual-IPM/-/issues>`__
* `Virtual-IPM on PyPI <https://pypi.org/project/virtual-ipm/>`__



.. |Maintenance yes| image:: https://img.shields.io/badge/maintained-yes-success.svg
   :target: https://gitlab.com/IPMsim/Virtual-IPM/-/releases

.. |PyPI version| image:: https://img.shields.io/pypi/v/virtual-ipm.svg
   :target: https://pypi.org/project/virtual-ipm/

.. |GPLv3 license| image:: https://img.shields.io/badge/license-AGPLv3-blue.svg
   :target: https://www.gnu.org/licenses/agpl-3.0.html

.. |PyPI pyversions| image:: https://img.shields.io/pypi/pyversions/virtual-ipm.svg
   :target: https://pypi.org/project/virtual-ipm/

.. |PyPI status| image:: https://img.shields.io/badge/status-stable-success.svg
   :target: https://pypi.org/project/virtual-ipm/

.. |Documentation Status| image:: https://img.shields.io/badge/documentation-yes-success.svg
   :target: https://ipmsim.gitlab.io/Virtual-IPM/
