From d0a5cf6d13dab7074e6a9ddea689bbb43713e662 Mon Sep 17 00:00:00 2001 From: Hannes T <80697868+s9105947@users.noreply.github.com> Date: Fri, 18 Mar 2022 15:42:16 +0000 Subject: [PATCH 1/3] add developer documentation and design principles New section "Developer Documentation" is aimed at developers wanting to work on PICMI itself. Its content may be of interest to implementors, but should not be required knowledge to them. The design principles outlines fundamental design decisions and aims to clarify misunderstandings on PICMI at an early stage. --- Docs/source/developer/design_principles.rst | 133 ++++++++++++++++++++ Docs/source/developer/developer.rst | 10 ++ Docs/source/index.rst | 1 + 3 files changed, 144 insertions(+) create mode 100644 Docs/source/developer/design_principles.rst create mode 100644 Docs/source/developer/developer.rst diff --git a/Docs/source/developer/design_principles.rst b/Docs/source/developer/design_principles.rst new file mode 100644 index 0000000..12477cd --- /dev/null +++ b/Docs/source/developer/design_principles.rst @@ -0,0 +1,133 @@ +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, ie. 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 be 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 conviently 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 if convenient. (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. They are + stored to be retrievable by the code. +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 +results in **undefined behavior**. + +Implementing codes may invoke checks on PICMI objects to ensure their +integrity. + +Types +~~~~~ + +For simplicitly **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 From 1e4f5a83f44f3fe31366293b26e9f5e2c4224e80 Mon Sep 17 00:00:00 2001 From: Hannes T <80697868+s9105947@users.noreply.github.com> Date: Tue, 22 Mar 2022 14:07:38 +0000 Subject: [PATCH 2/3] design principles: typos, rewording --- Docs/source/developer/design_principles.rst | 27 +++++++++++---------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/Docs/source/developer/design_principles.rst b/Docs/source/developer/design_principles.rst index 12477cd..8deadcc 100644 --- a/Docs/source/developer/design_principles.rst +++ b/Docs/source/developer/design_principles.rst @@ -7,7 +7,7 @@ Main Structure -------------- PICMI defines a Python interface to specify a PIC input parameter set. -It is not a pure schema, ie. can do computation. +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 @@ -21,7 +21,7 @@ PICMI is (aims to be) well-defined enough to compare codes. Scope ----- -PICMI aims to be define all parameters for most PIC scenarios. Obscure +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 @@ -31,11 +31,11 @@ Grouping Principles ------------------- Parameters defining physics are separated from parameters defining -numerics (i.e. how these physics are represented in the simulation). +numerics (i. e. how these physics are represented in the simulation). Parameters should be optional if possible. -Parameters are grouped conviently for the user: Classes may contain more +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. @@ -51,7 +51,7 @@ performed automatically. “Computations” here are filling in different representations of the same input data. -Redundancies are allowed if convenient. (e.g. laser a0/e0) +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 @@ -64,24 +64,25 @@ PICMI Object Lifecycle ~~~~~~~~~~~~~~~~~~~~~~ 0. Parameters are collected/loaded/created by the user. -1. PICMI object is constructed, **all** parameters are passed. They are - stored to be retrievable by the code. +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 -results in **undefined behavior**. +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. +Implementing codes may invoke checks on PICMI objects to ensure their integrity. Types ~~~~~ -For simplicitly **strong typing** is used, i.e. variables are checked +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 @@ -112,7 +113,7 @@ 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 +It is not a library, i. e. it does not provide functionality to be used by the implementation. Safety From 7e734177457aef2da566cdbce893a64fea8b368f Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Thu, 8 Sep 2022 10:07:40 -0700 Subject: [PATCH 3/3] Fix formatting: Quotes (ASCII) --- Docs/source/developer/design_principles.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Docs/source/developer/design_principles.rst b/Docs/source/developer/design_principles.rst index 8deadcc..252ad3a 100644 --- a/Docs/source/developer/design_principles.rst +++ b/Docs/source/developer/design_principles.rst @@ -48,7 +48,7 @@ Computations inside PICMI PICMI defines a parameter structure. Convenient computations are performed automatically. - “Computations” here are filling in different representations of the + "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). @@ -85,7 +85,7 @@ 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 +types (e.g. iterable instead of "list"), and (2) common library types (e.g. numpy types). Identifying Objects