picongpu.pypicongpu.species.operation

Submodules

• picongpu.pypicongpu.species.operation.densityoperation
• picongpu.pypicongpu.species.operation.densityprofile
• picongpu.pypicongpu.species.operation.momentum
• picongpu.pypicongpu.species.operation.noboundelectrons
• picongpu.pypicongpu.species.operation.notplaced
• picongpu.pypicongpu.species.operation.operation
• picongpu.pypicongpu.species.operation.setchargestate
• picongpu.pypicongpu.species.operation.simpledensity
• picongpu.pypicongpu.species.operation.simplemomentum

Classes

Operation	Defines the initialization of a set of attributes across multiple species
DensityOperation	common interface for all operations that create density
SimpleDensity	Place a set of species together, using the same density profile
NotPlaced	assigns a position attribute, but does not place a species
SimpleMomentum	provides momentum to a species
NoBoundElectrons	assigns a BoundElectrons attribute, but leaves it a 0
SetChargeState	assigns boundElectrons attribute and sets it to the initial charge state

Package Contents

class picongpu.pypicongpu.species.operation.Operation

Bases: picongpu.pypicongpu.rendering.RenderedObject

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

__hash__()

custom hash function for indexing in dicts

get_rendering_context() → dict | None

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 violation :raise RuntimeError: on schema not found :return: self as rendering context

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

check if the given context is valid for the given type

Raises on error, passes silently if okay.

Raises:

• ValidationError – on schema violation

• RuntimeError – on schema not found

class picongpu.pypicongpu.species.operation.DensityOperation

Bases: picongpu.pypicongpu.species.operation.operation.Operation

common interface for all operations that create density

and the not-placed operation

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

__hash__()

custom hash function for indexing in dicts

get_rendering_context() → dict | None

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 violation :raise RuntimeError: on schema not found :return: self as rendering context

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

check if the given context is valid for the given type

Raises on error, passes silently if okay.

Raises:

• ValidationError – on schema violation

• RuntimeError – on schema not found

class picongpu.pypicongpu.species.operation.SimpleDensity

Bases: picongpu.pypicongpu.species.operation.densityoperation.DensityOperation

Place a set of species together, using the same density profile

These species will have the same macroparticle placement.

For this operation, only the random layout is supported.

parameters:

• ppc: particles placed per cell

• profile: density profile to use

• species: species to be placed with the given profile note that their density ratios will be respected

ppc

particles per cell (random layout), >0

profile

density profile to use, describes the actual density

species

species to be placed

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.)

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.

attributes_by_species

attributes (exclusively) initialized by this operation

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

__hash__()

custom hash function for indexing in dicts

get_rendering_context() → dict | None

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 violation :raise RuntimeError: on schema not found :return: self as rendering context

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

check if the given context is valid for the given type

Raises on error, passes silently if okay.

Raises:

• ValidationError – on schema violation

• RuntimeError – on schema not found

class picongpu.pypicongpu.species.operation.NotPlaced

Bases: picongpu.pypicongpu.species.operation.densityoperation.DensityOperation

assigns a position attribute, but does not place a species

Intended for electrons which do not have a profile, but are used in pre-ionization.

Provides attributes Position & Weighting.

species

species which will not be placed

ppc = 0

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.)

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.

attributes_by_species

attributes (exclusively) initialized by this operation

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

__hash__()

custom hash function for indexing in dicts

get_rendering_context() → dict | None

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 violation :raise RuntimeError: on schema not found :return: self as rendering context

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

check if the given context is valid for the given type

Raises on error, passes silently if okay.

Raises:

• ValidationError – on schema violation

• RuntimeError – on schema not found

class picongpu.pypicongpu.species.operation.SimpleMomentum

Bases: picongpu.pypicongpu.species.operation.operation.Operation

provides momentum to a species

specified by:

• temperature

• drift

Both are optional. If both are missing, momentum is still provided, but left at 0 (default).

species

species for which momentum will be set

temperature

temperature of particles (if any)

drift

drift of particles (if any)

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.)

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.

attributes_by_species

attributes (exclusively) initialized by this operation

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

__hash__()

custom hash function for indexing in dicts

get_rendering_context() → dict | None

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 violation :raise RuntimeError: on schema not found :return: self as rendering context

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

check if the given context is valid for the given type

Raises on error, passes silently if okay.

Raises:

• ValidationError – on schema violation

• RuntimeError – on schema not found

class picongpu.pypicongpu.species.operation.NoBoundElectrons

Bases: picongpu.pypicongpu.species.operation.operation.Operation

assigns a BoundElectrons attribute, but leaves it a 0

Intended use for fully ionized ions, which do CAN be ionized. (Fully ionized ions which can NOT be ionized do not require a BoundElectrons attribute, and therefore no operation to assign it.)

species

species which will have BoundElectrons set to 0

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.)

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.

attributes_by_species

attributes (exclusively) initialized by this operation

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

__hash__()

custom hash function for indexing in dicts

get_rendering_context() → dict | None

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 violation :raise RuntimeError: on schema not found :return: self as rendering context

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

check if the given context is valid for the given type

Raises on error, passes silently if okay.

Raises:

• ValidationError – on schema violation

• RuntimeError – on schema not found

class picongpu.pypicongpu.species.operation.SetChargeState

Bases: picongpu.pypicongpu.species.operation.operation.Operation

assigns boundElectrons attribute and sets it to the initial charge state

used for ionization of ions

species

species which will have boundElectrons set

charge_state

number of bound electrons to set

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.)

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.

attributes_by_species

attributes (exclusively) initialized by this operation

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

__hash__()

custom hash function for indexing in dicts

get_rendering_context() → dict | None

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 violation :raise RuntimeError: on schema not found :return: self as rendering context

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

check if the given context is valid for the given type

Raises on error, passes silently if okay.

Raises:

• ValidationError – on schema violation

• RuntimeError – on schema not found