picongpu.pypicongpu.species.operation.operation

This file is part of the PIConGPU. Copyright 2021-2023 PIConGPU contributors Authors: Hannes Troepgen, Brian Edward Marre License: GPLv3+

Module Contents

Classes

Operation

Defines the initialization of a set of attributes across multiple species
class picongpu.pypicongpu.species.operation.operation.Operation

Bases: picongpu.pypicongpu.rendering.RenderedObject

Inheritance diagram of picongpu.pypicongpu.species.operation.operation.Operation

Defines the initialization of a set of attributes across multiple species

One attribute of one species is initialized by exactly one Operation.

May require the species to have certain constants.

Operations are treated strictly independently from one another. Dependencies are thus handled inside of a single Operation. (Note: The code generation may impose a custom order between the types of operations.)

All Operations combined generate the PIConGPU init pipeline.

This leads to some notable cases:

  • Species that are to be placed together (ion+electrons) must be initialized by the same Operation.

  • Dependent attributes must be initialized by the same Operation.

The typical lifecycle of an Operation object is as follows:

  1. Get created (i.e. __init__() is called)

    • performed from outside (PICMI interface)

    • affected species & parameters passed from outside (store as class attribute)

  2. check preconditions for passed species

    • params set correctly

    • required constants present in species

    • At the point of checking the given species object are not fully defined yet: DO NOT CHECK FOR OTHER ATTRIBUTES, THEY WILL NOT BE THERE!!!

    • operation-implemented in self.check_preconditions()

  3. prebook attributes (for each species)

    • generate attribute objects

    • “bookmark” that this operation will add them to the species, but does NOT assign the attributes (see 4.)

    • stored inside self.attributes_by_species

    • operation-implemented in self.prebook_species_attributes()

  4. associate generated attributes with their respective species

    • invoked by the initmanager (do not do this in this class)

    • based on self.attributes_by_species

    • (performed by pre-defined self.bake_species_attributes())

So to define your own operator:

  • inherit from this class

  • accept species list & additional params from users (and store in attributes of self) -> no pre-defined interface, define your own

  • implement self.check_preconditions() -> check for required constants etc.

  • implement self.prebook_species_attributes() -> fill self.attributes_by_species

Then use your operator somewhere and register it with the InitializationManager, which will make calls to the functions above, check for incompatibilities to other operators and finally associates the generated attributes to their species.

attributes_by_species

attributes (exclusively) initialized by this operation

abstract check_preconditions() → None

check own parameters and species this operator will be applied to

Must be implemented (overwritten) by the operator.

Throws if a precondition is not met, and passes silently if everything is okay.

If this operator relies on certain constants of classes to be set, (e.g. mass, charge) this must be checked here.

All parameters, including the species this Operator is to be applied to must be passed beforehand. Note: there is no unified way of passing parameters, please define your own. (Rationale: The structure of parameters is very heterogeneous.)

abstract prebook_species_attributes() → None

fills attributes_by_species

Must be implemented (overwritten) by the operator.

Generates the Attribute objects and pre-books them together with the species they are to be initialized for in self.attributes_by_species.

Will only be run after self.check_preconditions() has passed.

Note: Additional checks are not required, compatibility to other operations will be ensured from outside.

MUST NOT MODIFY THE SPECIES.

bake_species_attributes() → None

applies content of attributes_by_species to species

For each species in attributes_by_species.keys() assigns the attributes to their respective species, precisely appends to the list Species.attributes

Expects check_preconditions() and prebook_species_attributes() to have passed previously (without error).

Additionally, performs the following sanity checks:

  • at least one attribute is assigned

  • the species does not already have an attribute of the same type

  • every attribute is assigned exclusively to one species

Intended usage:

  1. check for dependencies in used species

  2. fill self.attributes_by_species (with newly generated objects) must be performed by self.prebook_species_attributes()

  3. call self.bake_species_attributes() (this method) to set species.attributes accordingly

get_rendering_context() → dict

get rendering context representation of this object

delegates work to _get_serialized and invokes checks performed by check_context_for_type(). :raise ValidationError: on schema violiation :raise RuntimeError: on schema not found :return: self as rendering context

static check_context_for_type(type_to_check: type, context: dict) → None

check if the given context is valid for the given type

Raises on error, passes silently if okay.

Raises:

  • ValidationError – on schema violiation

  • RuntimeError – on schema not found