diff --git a/Docs/source/developer/design_principles.rst b/Docs/source/developer/design_principles.rst new file mode 100644 index 0000000..252ad3a --- /dev/null +++ b/Docs/source/developer/design_principles.rst @@ -0,0 +1,134 @@ +Design Principles +================= + +This document describes fundamental design choices of PICMI. + +Main Structure +-------------- + +PICMI defines a Python interface to specify a PIC input parameter set. +It is not a pure schema, i. e. can do computation. + +In practical terms, PICMI defines a set of classes which implementations +must inherit from with well-defined names. These classes’ main purpose +is to provide a common user experience. + +Semantics +--------- + +PICMI is (aims to be) well-defined enough to compare codes. + +Scope +----- + +PICMI aims to define all parameters for most PIC scenarios. Obscure +parameters may be implemented by codes when needed. + + Rule of thumb: If multiple codes implement a feature, put it into + PICMI. + +Grouping Principles +------------------- + +Parameters defining physics are separated from parameters defining +numerics (i. e. how these physics are represented in the simulation). + +Parameters should be optional if possible. + +Parameters are grouped conveniently for the user: Classes may contain more +than the *minimal required set of parameters*, or in other terms: +Forming sub-groups of parameters is only done when **convenient**, not +mereley because sub-grouping would be possible. + +One PICMI object *should* represent one physical thing. + +Computations inside PICMI +------------------------- + +PICMI defines a parameter structure. Convenient computations are +performed automatically. + + "Computations" here are filling in different representations of the + same input data. + +Redundancies are allowed, though should be limited to different representations of a physical concept (e.g. laser a0/e0). +Inconsistencies must be caught by checks when invoked explicitly. + +Python Features +--------------- + +PICMI is implemented using Python. This section addresses some practical +approaches to the behavior and treatment of PICMI objects. + +PICMI Object Lifecycle +~~~~~~~~~~~~~~~~~~~~~~ + +0. Parameters are collected/loaded/created by the user. +1. PICMI object is constructed, **all** parameters are passed. + Automated computations are invoked. + Their results and the original parameters are stored to be retrievable by the code. + Note that the variables are exposed to the implementing code, not necessarily to the user. +2. The implementing code extracts these parameters. + +PICMI objects mainly hold data and are not designed to be modified +after they have been initialized with their content. + +Note that even if not recommended direct access to member variables +of objects is still possible. +Accessing the member variables directly (both reading and writing) results in **undefined behavior**. + +Implementing codes may invoke checks on PICMI objects to ensure their integrity. + +Types +~~~~~ + +For simplicity **strong typing** is used, i.e. variables are checked +against a finite list of type specifications. However, this finite list +of type specifications is kept **permissive**, including (1) general +types (e.g. iterable instead of "list"), and (2) common library types +(e.g. numpy types). + +Identifying Objects +~~~~~~~~~~~~~~~~~~~ + +Two PICMI objects are considered to be equal (and hence should yield the +same simulation initialization) if they fullfill the Python equals +operator (``__eq__()``, invoked by ``==``). + +PICMI reserves the option to redefine ``__eq__()`` to follow either of +these approaches: + +- Two PICMI objects are considered equal if all their attributes are equal (dataclass approach). +- Two PICMI objects are considered equal if they point to the same object, + i.e. the same memory region (python ``is`` operator, python vanilla for custom objects). + +Friendly towards Implementations +-------------------------------- + +It should be *easy* to implement PICMI. + +Extensible +~~~~~~~~~~ + +PICMI passes through all arguments (including codespecific variables) +which can be handled by implementations. + +It is not a library, i. e. it does not provide functionality to be used +by the implementation. + +Safety +~~~~~~ + +PICMI aims to provide a well defined interface to implementing codes. +PICMI guarantees the integrity of its structure by providing ``check()`` +methods, which can be called explicitly. + +PICMI is **predictable** in the sense that any variable provided by the +user is passed through to the implementation using **the same name**. + +Implementations are not Bound by PICMI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Implementations may extend PICMI at arbitrary points. PICMI provides +simple interfaces for that. Implementations may only implement PICMI +partially. diff --git a/Docs/source/developer/developer.rst b/Docs/source/developer/developer.rst new file mode 100644 index 0000000..e89f1bb --- /dev/null +++ b/Docs/source/developer/developer.rst @@ -0,0 +1,10 @@ +Developer Documentation +======================= + +This section is aimed at the developer of PICMI and guide them through general design and internal functionality of PICMI itself, i.e. the python module ``picmistandard``. +It does **not** explain how to implement PICMI in an existing PIC simulation. + +.. toctree:: + :maxdepth: 1 + + design_principles diff --git a/Docs/source/index.rst b/Docs/source/index.rst index b564a48..23bc739 100644 --- a/Docs/source/index.rst +++ b/Docs/source/index.rst @@ -31,3 +31,4 @@ For more details on the standard and how to use it, see the links below. how_to_use/how_to_use.rst standard/standard.rst + developer/developer.rst