Metadata-Version: 2.1
Name: picmistandard
Version: 0.32.0
Summary: Python base classes for PICMI standard
License: PICMI/AMI v0.0.1 Copyright (c) 2018, The Regents of the University of California, through Lawrence Berkeley National Laboratory, and Lawrence Livermore National Security, LLC, for the operation of Lawrence Livermore National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
        
        
        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
        
        
        (1) Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
        
        (2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
        
        (3) Neither the name of the University of California, Lawrence Berkeley National Laboratory, Lawrence Livermore National Security, LLC, Lawrence Livermore National Laboratory, U.S. Dept. of Energy, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        
        You are under no obligation whatsoever to provide any bug fixes, patches, or upgrades to the features, functionality or performance of the source code ("Enhancements") to anyone; however, if you choose to make your Enhancements available either publicly, or directly to Lawrence Berkeley National Laboratory, without imposing a separate written license agreement for such Enhancements, then you hereby grant the following license: a non-exclusive, royalty-free perpetual license to install, use, modify, prepare derivative works, incorporate into other computer software, distribute, and sublicense such enhancements or derivative works thereof, in binary and source code form.
        
Project-URL: Repository, https://github.com/picmi-standard/picmi
Project-URL: Documentation, https://picmi.readthedocs.io/en/latest
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: User Interfaces
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.15
Requires-Dist: scipy~=1.5

# PICMI

The *Particle-In-Cell Modeling Interface* (**PICMI**) standard establishes conventions for the naming and structuring of input files for Particle-In-Cell simulations.

The goal of the standard is to propose a set (or dictionary) of names and definitions that can be used in simulations, with as little changes as possible between codes.

Just as two persons do generally not use the exact same set of words from a dictionary (whatever the language), each code will use syntax (associated with unique functionalities of the code) that others will not. However, it is expected that, just like two persons will use and understand the same words and syntax for the most common topics, codes will share the same language for common definitions and tasks.

For example, it is expected that most PIC codes can share the same syntax to define a grid, a commonly-used field solver, a set of particles, etc. On the other hand, only a subset of the codes will offer, e.g. mesh refinement, field ionization, or code steering by the user. In this case, it is up to the implementation with each code to decide whether to ignore, raise a warning or an error, when an undefined statement is encountered. For more flexibility and robustness, conditional statements are available to the user to execute or read lines of the input script, based on the targeted code.

The intent is for the standard to be agnostic of the language of implementation, which can then potentially be performed using JSON, Python, FORTRAN or other means.

**Warning:**
The standard is still evolving at this point. The most basic components of the standard have been defined and are being refined. New components are being added.

# Contents of this repository

This repository contains:

- A set of **example scripts** that use the PICMI standard (in the directory `Examples`)

- A **Python package** that contains the base classes for the implementation of the PICMI standard (in the directory `PICMI_Python`). It is best to install the package from PyPI:
  ```
  pip install picmistandard
  ```
  Optionally, it can be installed from the source (run from the main directory where the pyproject.toml file is).
  ```
  python -m pip install .
  ```
  (The code will be automatically uploaded to PyPI upon creation of a new release on Github.)

- The sources to generate the **Sphinx documentation** for the PICMI standard (in the directory `Docs`). In order to generate the Sphinx documentation, first install [Sphinx](http://www.sphinx-doc.org/en/master/), as well as the version of the PICMI standard that you would like to document (e.g. via `python setup.py`). Then type:
  ```
  cd Docs
  make html
  ```
  You can then view the documentation by opening the file `Docs/build/html/index.html` with a standard web browser.
