picongpu.pypicongpu

internal representation of params to generate PIConGPU input files

Submodules

• picongpu.pypicongpu.customuserinput
• picongpu.pypicongpu.grid
• picongpu.pypicongpu.laser
• picongpu.pypicongpu.movingwindow
• picongpu.pypicongpu.output
• picongpu.pypicongpu.rendering
• picongpu.pypicongpu.runner
• picongpu.pypicongpu.simulation
• picongpu.pypicongpu.solver
• picongpu.pypicongpu.species
• picongpu.pypicongpu.util

Classes

Simulation	Represents all parameters required to build & run a PIConGPU simulation.
Runner	Accepts a PyPIConGPU Simulation and runs it
PhaseSpace	general interface for all plugins
EnergyHistogram	general interface for all plugins
MacroParticleCount	general interface for all plugins

Package Contents

class picongpu.pypicongpu.Simulation

Bases: picongpu.pypicongpu.rendering.RenderedObject

Represents all parameters required to build & run a PIConGPU simulation.

Most of the individual parameters are delegated to other objects held as attributes.

To run a Simulation object pass it to the Runner (for details see there).

delta_t_si

Width of a single timestep, given in seconds.

time_steps

Total number of time steps to be executed.

grid

Used grid Object

laser

Used (gaussian) Laser

solver

Used Solver

init_manager

init manager holding all species & their information

typical_ppc

typical number of macro particles spawned per cell, >=1

used for normalization of units

custom_user_input

object that contains additional user specified input parameters to be used in custom templates

@attention custom user input is global to the simulation

moving_window

used moving Window, set to None to disable

plugins

__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.Runner(sim, pypicongpu_template_dir: str | None = None, scratch_dir: str | None = None, setup_dir: str | None = None, run_dir: str | None = None)

Accepts a PyPIConGPU Simulation and runs it

Manages 2 basic parts:

• where which data is stored (various ..._dir options)

• what is done (generate, build, run)

Where:

• scratch_dir: (optional) directory where many simulation results can be stored

• run_dir: directory where data for an execution is stored

• setup_dir: directory where data is generated to and the simulation executable is built

These dirs are either copied from params or guessed. See __init__() for a detailed description.

The initialization of the dirs happens only once (!) inside __init__(). Any changes performed after that will be accepted and might lead to broken builds.

What:

• generate(): create a setup (directory) which represents the parameters given

• build(): run pic-build

• run(): run tbg

Typically these can only be performed in that order, and each once. Whether a step can be started is determined by some sanity checks: Are the inputs (e.g. the setup dir, the .build dir) ready, and is the output location empty (e.g. the run dir). If those sanity checks pass, the respective process is launched. If this launched program (e.g. pic-build) fails, the process output (stdout & stderr) is printed. While a process is running, all output is silenced (and collected into an internal buffer).

SCRATCH_ENV_NAME = 'SCRATCH'

name of the environment variable where the scratch dir defaults to

setup_dir

directory containing the experiment setup (scenario)

pic-build is called here

scratch_dir

directory where run directories can be store

run_dir

directory where run results (and a copy of the inputs) will be stored

sim

the picongpu simulation to be run

generate(printDirToConsole=False)

generate the picongpu-compatible input files

build()

build (compile) picongpu-compatible input files

run()

run compiled picongpu simulation

class picongpu.pypicongpu.PhaseSpace

Bases: picongpu.pypicongpu.output.plugin.Plugin

general interface for all plugins

species

period

spatial_coordinate

momentum_coordinate

min_momentum

max_momentum

check()

get_generic_plugin_rendering_context() → dict

retrieve a context valid for “any plugin”

Problem: Every plugin has its respective schema, and it is difficult in JSON (particularly in a mustache-compatible way) to get the type of the schema.

Solution: The normal rendering of plugins get_rendering_context() provides only their parameters, i.e. there is no meta information on types etc.

If a generic plugin is requested one can use the schema for “Plugin” (this class), for which this method returns the correct content, which includes metainformation and the data on the schema itself.

E.g.:

{
    "type": {
        "phasespace": true,
        "auto": false,
        ...
    },
    "data": DATA
}

where DATA is the serialization as returned by get_rendering_context().

There are two context serialization methods for plugins:

• get_rendering_context()

  • provided by RenderedObject parent class, serialization (“context building”) performed by _get_serialized()

  • _get_serialized() implemented in every plugin

  • checks against schema of respective plugin

  • returned context is a representation of exactly this plugin

  • (left empty == not implemented in parent Plugin)

• get_generic_plugin_rendering_context()

  • implemented in parent class Plugin

  • returned representation is generic for any plugin (i.e. contains meta information which type is actually used)

  • passes information from get_rendering_context() through

  • returned representation is designed for easy use with templating engine mustache

__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.EnergyHistogram

Bases: picongpu.pypicongpu.output.plugin.Plugin

general interface for all plugins

species

period

bin_count

min_energy

max_energy

get_generic_plugin_rendering_context() → dict

retrieve a context valid for “any plugin”

Problem: Every plugin has its respective schema, and it is difficult in JSON (particularly in a mustache-compatible way) to get the type of the schema.

Solution: The normal rendering of plugins get_rendering_context() provides only their parameters, i.e. there is no meta information on types etc.

If a generic plugin is requested one can use the schema for “Plugin” (this class), for which this method returns the correct content, which includes metainformation and the data on the schema itself.

E.g.:

{
    "type": {
        "phasespace": true,
        "auto": false,
        ...
    },
    "data": DATA
}

where DATA is the serialization as returned by get_rendering_context().

There are two context serialization methods for plugins:

• get_rendering_context()

  • provided by RenderedObject parent class, serialization (“context building”) performed by _get_serialized()

  • _get_serialized() implemented in every plugin

  • checks against schema of respective plugin

  • returned context is a representation of exactly this plugin

  • (left empty == not implemented in parent Plugin)

• get_generic_plugin_rendering_context()

  • implemented in parent class Plugin

  • returned representation is generic for any plugin (i.e. contains meta information which type is actually used)

  • passes information from get_rendering_context() through

  • returned representation is designed for easy use with templating engine mustache

__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.MacroParticleCount

Bases: picongpu.pypicongpu.output.plugin.Plugin

general interface for all plugins

species

period

get_generic_plugin_rendering_context() → dict

retrieve a context valid for “any plugin”

Problem: Every plugin has its respective schema, and it is difficult in JSON (particularly in a mustache-compatible way) to get the type of the schema.

Solution: The normal rendering of plugins get_rendering_context() provides only their parameters, i.e. there is no meta information on types etc.

If a generic plugin is requested one can use the schema for “Plugin” (this class), for which this method returns the correct content, which includes metainformation and the data on the schema itself.

E.g.:

{
    "type": {
        "phasespace": true,
        "auto": false,
        ...
    },
    "data": DATA
}

where DATA is the serialization as returned by get_rendering_context().

There are two context serialization methods for plugins:

• get_rendering_context()

  • provided by RenderedObject parent class, serialization (“context building”) performed by _get_serialized()

  • _get_serialized() implemented in every plugin

  • checks against schema of respective plugin

  • returned context is a representation of exactly this plugin

  • (left empty == not implemented in parent Plugin)

• get_generic_plugin_rendering_context()

  • implemented in parent class Plugin

  • returned representation is generic for any plugin (i.e. contains meta information which type is actually used)

  • passes information from get_rendering_context() through

  • returned representation is designed for easy use with templating engine mustache

__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