Metadata-Version: 2.1
Name: virtual-ipm
Version: 2.2.1.post1
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
Platform: UNKNOWN
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: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
Requires-Dist: anna (>=0.4.1)
Requires-Dist: injector (==0.12.1)
Requires-Dist: ionics
Requires-Dist: numpy (>=1.18)
Requires-Dist: pandas
Requires-Dist: pyhocon
Requires-Dist: rich
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'

|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    |                 |                                         | Gas jets                   |
| Gaussian     | Gaussian       |                 |                                         |                            |
+--------------+----------------+-----------------+-----------------------------------------+----------------------------+
| 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/


