mewarpx package

Subpackages

Submodules

mewarpx.assemblies module

Assembly implementations.

class mewarpx.assemblies.Anode(z, V, T, WF, read_scraped_particles=True)[source]

Bases: ZPlane

A basic wrapper to define a semi-infinite plane for the anode.

Basic initialization.

Parameters

  • z (float) – The edge of the semi-infinite plane (m)

  • zsign (int) – =1 to extend from z to +inf, or =-1 to extend from -inf to z.

  • V (float) – Voltage (V)

  • T (float) – Temperature (K)

  • WF (float) – Work function (eV)

  • name (str) – Assembly name

class mewarpx.assemblies.Assembly(V, T, WF, name, read_scraped_particles)[source]

Bases: object

An assembly represents any shape in the simulation; usually a conductor.

While V, T, and WF are required, specific use cases may allow None to be used for these fields.

Basic initialization.

Parameters

  • V (float) – Voltage (V)

  • T (float) – Temperature (K)

  • WF (float) – Work function (eV)

  • name (str) – Assembly name

add_diag_fn(diag_fn, attrib_list)[source]

Add a diagnostic function to the diagnostic function list.

Parameters

  • diag_fn (function) – Function to be run after _read_scraped_particles() that processes the scraped particle dictionary for a specific diagnostic purpose.

  • attrib_list – (list of strings): Particle attributes that should be included in the scraped particle dictionary for the given diagnostic function.

check_geom()[source]

Throw an error if the simulation geometry is unsupported by the Assembly.

getvoltage()[source]

Allows for time-dependent implementations to override this.

getvoltage_e()[source]

Allows for time-dependent implementations to override this.

scraper_diag = None
class mewarpx.assemblies.Cathode(V, T, WF, read_scraped_particles=True)[source]

Bases: ZPlane

A basic wrapper to define a semi-infinite plane for the cathode.

Basic initialization.

Parameters

  • z (float) – The edge of the semi-infinite plane (m)

  • zsign (int) – =1 to extend from z to +inf, or =-1 to extend from -inf to z.

  • V (float) – Voltage (V)

  • T (float) – Temperature (K)

  • WF (float) – Work function (eV)

  • name (str) – Assembly name

class mewarpx.assemblies.CylinderZ(V, T, WF, name, r_outer, r_inner=0.0, zmin=None, zmax=None, read_scraped_particles=True)[source]

Bases: Assembly

A Cylinder pointing in the z-direction with center along the x and y origin line (to support RZ).

Basic initialization.

Parameters

  • V (float) – Voltage (V)

  • T (float) – Temperature (K)

  • WF (float) – Work function (eV)

  • name (str) – Assembly name

  • r_outer (float) – The outer radius of the cylinder (m)

  • r_inner (float) – The inner radius of the cylinder (m)

  • zmin (float) – Lower z limit of the cylinder (m). Defaults to mwxrun.zmin.

  • zmax (float) – Upper z limit of the cylinder (m). Defaults to mwxrun.zmax.

calculatenormal(px, py, pz)[source]

Calculates Normal of particle inside/outside of conductor to nearest surface of conductor

Parameters

  • px (np.ndarray) – x-coordinate of particle in meters.

  • py (np.ndarray) – y-coordinate of particle in meters.

  • pz (np.ndarray) – z-coordinate of particle in meters.

Returns

Normal of particles of conductor to nearest

surface of conductor.

Return type

nhat (np.ndarray)

geoms = ['RZ']
isinside(X, Y, Z, aura=0)[source]

Determines whether the given coordinates are inside the assembly.

Parameters

  • X (np.ndarray) – array of x coordinates.

  • Y (np.ndarray) – array of y coordinates.

  • Z (np.ndarray) – array of z coordinates.

  • aura (float) – extra space around the conductor that is considered inside. Useful for small, thin conductors that don’t overlap any grid points. In units of meters.

Returns

array of values corresponding to the input

coordinates where all points inside the assembly are 1, and others are 0.

Return type

result (np.ndarray)

class mewarpx.assemblies.InfCylinderY(center_x, center_z, radius, V, T, WF, name, install_in_simulation=True, read_scraped_particles=True)[source]

Bases: Assembly

An infinitely long Cylinder pointing in the y-direction.

Basic initialization.

Parameters

  • center_x (float) – The x-coordinates of the center of the cylinder. Coordinates are in (m)

  • center_z (float) – The z-coordinates of the center of the cylinder. Coordinates are in (m)

  • radius (float) – The radius of the cylinder (m)

  • V (float) – Voltage (V)

  • T (float) – Temperature (K)

  • WF (float) – Work function (eV)

  • name (str) – Assembly name

  • install_in_simulation (bool) – If True and the Assembly is an embedded boundary it will be included in the WarpX simulation

calculatenormal(px, py, pz)[source]

Calculates Normal of particle inside/outside of conductor to nearest surface of conductor

Parameters

  • px (np.ndarray) – x-coordinate of particle in meters.

  • py (np.ndarray) – y-coordinate of particle in meters.

  • pz (np.ndarray) – z-coordinate of particle in meters.

Returns

Normal of particles of conductor to nearest

surface of conductor.

Return type

nhat (np.ndarray)

geoms = ['XZ', 'XYZ']
isinside(X, Y, Z, aura=0)[source]

Determines whether the given coordinates are inside the assembly.

Parameters

  • X (np.ndarray) – array of x coordinates.

  • Y (np.ndarray) – array of y coordinates.

  • Z (np.ndarray) – array of z coordinates.

  • aura (float) – extra space around the conductor that is considered inside. Useful for small, thin conductors that don’t overlap any grid points. In units of meters.

Returns

array of values corresponding to the input

coordinates where all points inside the assembly are 1, and others are 0.

Return type

result (np.ndarray)

class mewarpx.assemblies.PatchyCathode(V, T, phi_bar, delta_phi, patch_size, read_scraped_particles=True)[source]

Bases: object

A basic wrapper to define a semi-infinite plane for a patchy cathode. Special aspects of the patchy cathode involve instantiation of two assembly objects for the low and high work-function patches of the cathode and setting a spatially varying boundary potential. Installing such a spatially varying boundary potential is simplified by using an embedded boundary rather than the domain boundary since WarpX does not yet support spatially varying boundary conditions on domain boundaries (as of 6/3/2022, and implementing it could hurt performance with constant potentials unless it is carefully done). Simplified assemblies similar to Rectangle is used.

Arguments:

V (float): Cathode fermi-level - phi_bar (far field vacuum level). T (float): Temperature of the cathode in Kelvin. phi_bar (float): Average work-function. delta_phi (float): Difference between max and min work-function values. patch_size (float): Patch size in meters.

geoms = ['XZ']
class mewarpx.assemblies.Rectangle(center_x, center_z, length_x, length_z, V, T, WF, name, install_in_simulation=True, read_scraped_particles=True)[source]

Bases: Assembly

A rectangular prism infinite in y.

Basic initialization.

Parameters

  • center_x (float) – The x-coordinates of the center of the rectangle. Coordinates are in (m)

  • center_z (float) – The z-coordinates of the center of the rectangle. Coordinates are in (m)

  • length_x (float) – The length the rectangle in the x direction (m)

  • length_z (float) – The length the rectangle in the z direction (m)

  • V (float) – Voltage (V)

  • T (float) – Temperature (K)

  • WF (float) – Work function (eV)

  • name (str) – Assembly name

  • install_in_simulation (bool) – If True and the Assembly is an embedded boundary it will be included in the WarpX simulation

calculatenormal(px, py, pz)[source]

Calculates Normal of particle inside/outside of conductor to nearest surface of conductor. Nearest surface of conductor is determined by the region of the transformed rectangle that the transformed particle belongs to.

The 4 regions in order from 0 - 3 are:
0: bottom portion of transformed rectangle and below transformed

rectangle (-y)

1: right portion of transformed rectangle and to the right of

transformed rectangle (+x)

2: top portion of transformed rectangle and above transformed

rectangle (+y)

3: left portion of transformed rectangle and to the left of

transformed rectangle (-x)

Parameters

  • px (np.ndarray) – x-coordinate of particle in meters.

  • py (np.ndarray) – y-coordinate of particle in meters.

  • pz (np.ndarray) – z-coordinate of particle in meters.

Returns

Normal of particles of conductor to nearest

surface of conductor.

Return type

nhat (np.ndarray)

geoms = ['XZ', 'XYZ']
isinside(X, Y, Z, aura=0)[source]

Determines whether the given coordinates are inside the assembly.

Parameters

  • X (np.ndarray) – array of x coordinates.

  • Y (np.ndarray) – array of y coordinates.

  • Z (np.ndarray) – array of z coordinates.

  • aura (float) – extra space around the conductor that is considered inside. Useful for small, thin conductors that don’t overlap any grid points. In units of meters.

Returns

array of values corresponding to the input

coordinates where all points inside the assembly are 1, and others are 0.

Return type

result (np.ndarray)

class mewarpx.assemblies.ZPlane(z, zsign, V, T, WF, name, read_scraped_particles=True)[source]

Bases: Assembly

A semi-infinite plane.

Basic initialization.

Parameters

  • z (float) – The edge of the semi-infinite plane (m)

  • zsign (int) – =1 to extend from z to +inf, or =-1 to extend from -inf to z.

  • V (float) – Voltage (V)

  • T (float) – Temperature (K)

  • WF (float) – Work function (eV)

  • name (str) – Assembly name

geoms = ['RZ', 'X', 'XZ', 'XYZ']
class mewarpx.assemblies.ZPlanePatchSet(V, T, WF, name, patch_size, x_start, z)[source]

Bases: ZPlane

A rectangle-like assembly that only scrapes on strips of width patch_size, with the same distance between neighboring strips, positioned such that a strip starts at x_start.

Same arguments as ZPlane, with the following additions:

patch_size (float): Width of strip to scrape from and distance

between strips.

x_start (float): x-position where a strip starts. z (float): z-position of the front face of the cathode.

isinside(X, Y, Z)[source]

Determines whether the given coordinates are inside the assembly.

Parameters

  • X (np.ndarray) – array of x coordinates.

  • Y (np.ndarray) – array of y coordinates.

  • Z (np.ndarray) – array of z coordinates.

Returns

array of values corresponding to the input

coordinates where all points inside the assembly are 1, and others are 0.

Return type

result (np.ndarray)

mewarpx.diags module

Hold aliases to all diagnostics so user does not need to remember particular namespaces.

mewarpx.emission module

Module for various types of particle emission in WarpX.

class mewarpx.emission.ArbitraryDistributionVolumeEmitter(d_grid, *args, **kwargs)[source]

Bases: VolumeEmitter

Varies density based on given particle density array. NPPC for each species must be an integer greater than or equal to 1.

Parameters

d_grid (np.ndarray) – array of particle densities given in cm^-3

geoms = ['XZ']
class mewarpx.emission.ArbitraryEmitter2D(conductor, T=None, res_fac=5.0, transverse_fac=1.0, **kwargs)[source]

Bases: Emitter

ArbitraryEmitter2D class takes in a conductor, calculates an approximate surface that encloses the conductor and then sets up the appropriate emitting surfaces, given a number of particles to emit.

Construct the emitter based on conductor object and temperature.

Parameters

  • conductor (mewarpx.assemblies object) – Conductor to emit from.

  • T (float) – Temperature in Kelvin. If not specified the temperature of the conductor will be used.

  • res_fac (float) – Level of resolution beyond the grid resolution to use for calculating shape contours.

  • transverse_fac (float) – Scale the transverse energy distribution by this factor. Default 1. See mewarpx.utils_store.util.get_velocities() for details.

  • kwargs (dict) – Any other keyword arguments supported by the parent Emitter constructor (such as “emission_type”).

static convert_vel_zhat_nhat(vels, nhat)[source]

Create a rotation matrix for Zhat to Nhat

geoms = ['XZ']
get_normals(x, y, z)[source]

Calculate local surface normal at specified coordinates. :param x: x-coordinates of emitted particles (in meters). :type x: np.ndarray :param y: y-coordinates of emitted particles (in meters). :type y: np.ndarray :param z: z-coordinates of emitted particles (in meters). :type z: np.ndarray

Returns

nx3 array containing the outward surface

normal vector at each particle location.

Return type

normals (np.ndarray)

plot_contours()[source]

Plots the contours generated for the assembly object and the assembly object. The object is plotted in yellow, and the contours are plotted in blue. The plot is saved in contours.png

class mewarpx.emission.BaseEmitter[source]

Bases: object

Parent class of both Emitter (which handles injection from a surface or other area) and VolumeEmitter (which handles injection throughout a volume).

All BaseEmitter objects are expected to contain:

  • get_newparticles() returns coordinates, velocities, and KE in a dict - implemented here

  • _get_xv_coords() implements the subclass-specific particle injection logic

  • getvoltage() calculates the potential energy for particle energies.

  • getvoltage_e() calculates the potential energy for particle energies including the work function.

  • geoms is a property containing a list of simulation geometries supported by the Emitter, as strings

Check geometry and any other universal initialization.

add_wfn(wfn)[source]

Add a variable weight function to the emitter.

Parameters

wfn (function) – This must take in a particle dictionary with positions, velocities, and existing weights, and return a new array of particle weights.

check_geom()[source]

Return the current solver geometry, or throw an error if it is unsupported by the Emitter.

geoms = []
get_newparticles(npart, w, q, m, rseed=None, randomdt=True, velhalfstep=True)[source]

Return dict with coordinates, velocities, and KE

Note

This function SHOULD (but doesn’t in WarpX yet) handle the random timestep advancement and the negative half-step velocity push. They can be turned off if desired. No leapfrogging is done in the initial random advancement, which could be a (hopefully very minor) source of error.

Parameters

  • npart (int) – Total number of particles to inject

  • w (float) – Weight of the particles

  • q (float) – Charge of the particles, usually species.sq.

  • m (float) – Mass of the particles, usually species.sm. Equals electron mass if not otherwise specified.

  • rseed (int) – Random seed, if specified, can be used to provide reproducible results. Typically used for test / not production runs.

  • randomdt (bool) – If True, move each particle ahead a random delta t in [0, dt), advancing both position and velocity together. Default True.

  • velhalfstep (bool) – If True, push the velocities a negative half-step using the E-field. Aligns position and velocities correctly for the leapfrog algorithm.

Returns

Contains lists, each with length equal to the number of particles:

  • x, y, and z contain initial positions

  • vx, vy, and vz contain initial velocities

  • E_total contains initial energy of each particle, kinetic & potential.

  • w contains particle weights.

Return type

particle_dict (dict)

getvoltage()[source]

This should return the potential energy at the injection site for fully accurate energetics.

getvoltage_e()[source]

This should return the potential energy, including work function, at the injection site for fully accurate energetics.

class mewarpx.emission.Emitter(T, conductor=None, emission_type='thermionic')[source]

Bases: BaseEmitter

Parent class for emission from a surface.

All Emitter objects are expected to contain:

  • area is a property containing the area in m^2

  • cell_count is a property containing the number of mesh cells spanned by the Emitter

  • geoms is a property containing a list of simulation geometries supported by the Emitter

  • _get_xv_coords() implements the subclass-specific particle injection logic

  • get_normals() returns the normals for a set of particle coordinates.

Default initialization for all Emitter objects.

Parameters

  • T (float) – Emitter temperature in Kelvin. Determines particle velocity distribution. If None, the temperature of the conductor will be used if one is specified.

  • conductor (assemblies.Assembly) – Conductor the emitter is attached to, used for recording initial voltages and energies. If None, V_e is set to 0. Since there’s no current use case for this, a warning is printed.

  • emission_type (str) – Distribution function type used to sample velocities of the emitted particles. Must be defined in mewarpx.utils_store.util.get_velocities(). Defaults to ‘thermionic’.

area = None
cell_count = None
geoms = []
get_normals(x, y, z)[source]

Calculate local surface normal at specified coordinates.

Parameters

  • x (np.ndarray) – x-coordinates of emitted particles (in meters).

  • y (np.ndarray) – y-coordinates of emitted particles (in meters).

  • z (np.ndarray) – z-coordinates of emitted particles (in meters).

Returns

nx3 array containing the outward surface

normal vector at each particle location.

Return type

normals (np.ndarray)

getvoltage()[source]

This should return the potential energy at the injection site for fully accurate energetics.

getvoltage_e()[source]

Electrical voltage includes WF, eg the Fermi level voltage.

class mewarpx.emission.FixedNumberInjector(emitter, species, npart, injectfreq=None, injectoffset=1, weight=0.0, rseed=None, name=None, unique_particles=True)[source]

Bases: Injector

Inject n particles every t timesteps.

Sets up user-specified injection with fixed timestep and weights.

Parameters

  • emitter (mewarpx.emission.BaseEmitter) – Emitter object that will specify positions and velocities of particles to inject.

  • species (picmi.Species) – Premade species to inject particles of.

  • npart (int) – Number of particles to inject total

  • injectfreq (int) – Number of steps to wait for next injection. Default infinity.

  • injectoffset (int) – First timestep to inject. Default 1 (the first possible timestep in WarpX).

  • weight (float) – Macroparticle weight to be introduced.

  • rseed (int) – If specified, all injection should be repeatable using this rseed. At present each set of injected particles will have the same initial position and velocities as the previous set.

  • name (str) – Injector name for diagnostics. Constructed from speciesname if not given.

  • unique_particles (bool) – Whether WarpX will keep all particles given it from every processor (True) or keep only a fraction of particles based on processor count (False).

inject_particles()[source]

Perform the actual injection!

class mewarpx.emission.Injector[source]

Bases: object

Base class for injection. All injectors must include an emitter object, and should also include a ‘name’ field for diagnostics.

append_injectedparticles(data)[source]

Append one or more lines of injected particles data.

Parameters

data (np.ndarray) – Array of shape (m) or (n, m) where m is the number of fields and n is the number of rows of data to append.

static compute_npart(npart_total, unique_particles)[source]

Compute number of particles to insert at a given timestep.

This function translates between total particle number and this processor’s particle numbers. If particles are designated “unique”, none are discarded by WarpX so we have logic here to give the processor the right number of particles, with additional logic to load-balance the remainder. If unique_particles is False, WarpX essentially does the particle discarding, so each processor should inject the whole number of particles to start.

Parameters

  • npart_total (int) – Integer number of total particles to insert this timestep.

  • unique_particles (bool) – If True, WarpX keeps all particles sent to it. If False, it only keeps a processor’s fraction of total particles.

Returns

Integer number of total particles for this processor

to insert this timestep.

Return type

npart (int)

emitter = None
fields = ['t', 'step', 'species_id', 'V_e', 'n', 'q', 'E_total']
get_injectedparticles(clear=False)[source]

Retrieve a copy of injectedparticles data.

Parameters

clear (bool) – If True, clear the particle data rows entered (field names are still initialized as before). Default False.

Returns

Keys are the

originally passed field strings for lost particles. Values are an (n)-shape numpy array for each field.

Return type

injectedparticles_dict (collections.OrderedDict)

getvoltage_e()[source]

Return the electrical voltage of the injector. Defaults to returning 0, unless an emitter is associated with this injector (it should be) in which case return the emitter’s electrical voltage. Child classes can override this if needed.

init_injectedparticles(fieldlist)[source]

Set up the injected particles array. Call before append_injectedparticles.

Parameters

fieldlist (list) – List of string titles for the fields. Order is important; it must match the order for future particle appends that are made.

injector_diag = None
record_injectedparticles(species, w=0, E_total=None, n=None)[source]

Handles transforming raw particle information to the information used to record particles as a function of time. Also handles parallel sum and appending to the data array the current amount of injection.

Note

Assumes the fixed form of fields given in Injector(). Doesn’t check since this is called many times. Since a parallelsum is performed on _injectedparticles_data when calling get_injectedparticles, this function has to be called by all processors. Call this function with only the species argument if no particles are being added by this processor.

Parameters

  • species (mewarpx.mespecies.Species) – Species of particle

  • w (np.ndarray or float) – Array of length npart with particle weights

  • E_total (np.ndarray or float) – Array of length npart with E_total values.

  • n (int) – Number of macroparticles, _only_ needed if overriding the length of E_total. This is useful mostly in the case that E_total is already summed over particles, in which case a single number can be passed for it rather than an array.

class mewarpx.emission.PlasmaInjector(emitter, species1, species2, npart, T_2=None, plasma_density=None, ionization_frac=None, P_neutral=None, T_neutral=None, injectfreq=None, injectoffset=1, rseed=None, name=None, unique_particles=True)[source]

Bases: Injector

Inject particles at simulation start, or at regular timesteps, to seed a plasma. Can use any emitter object. The defining feature is that the 2nd species positions and weights are copied from the first species, so the spatial distribution is always identical to start. Velocities are independent, however.

Initialize injection of a plasma with two species and given emitter.

Parameters

  • emitter (mewarpx.emission.BaseEmitter) – BaseEmitter object that will specify positions and velocities of particles to inject.

  • species1 (mewarpx.mespecies.Species) – First species, eg electron

  • species2 (mewarpx.mespecies.Species) – Second species, eg ion

  • npart (int) – Number of macroparticles to inject total among all processors and species.

  • T_2 (float) – If specified, species2 will be injected at this temperature.

  • plasma_density (float) – Ion number density to inject. If using volumetric emitter, in m^(-3), if using surface emitter, in m^(-2)

  • ionization_frac (float) – Instead of plasma_density, use a specific ionization fraction of the neutral gas. Volumetric emitter only.

  • P_neutral (float) – If using ionization_frac only, the neutral gas density (Torr).

  • T_neutral (float) – If using ionization_frac only, the neutral gas temperature (K).

  • injectfreq (int) – Number of steps to wait for next injection. Default infinity.

  • injectoffset (int) – First timestep to inject. Default 1 (the first possible timestep in WarpX).

  • rseed (int) – If specified, all injection should be repeatable using this rseed. At present each set of injected particles will have the same initial position and velocities as the previous set.

  • name (str or None) – Injector name for diagnostics. Constructed from species names if not given.

  • unique_particles (bool) – Whether WarpX will keep all particles given it from every processor (True) or keep only a fraction of particles based on processor count (False). Default True.

inject_particles()[source]

Inject particles, same position & weight for each.

class mewarpx.emission.ThermionicInjector(emitter, species, npart_per_cellstep, T=None, WF=None, A=<MagicMock name='mock.m_e.__rmul__().__mul__().__mul__().__truediv__().__mul__().__mul__()' id='139933669787584'>, use_Schottky=True, Schottky_factor=1.0, allow_poisson=False, wfac=1.0, name=None, profile_decorator=None, unique_particles=True)[source]

Bases: Injector

Performs standard every-timestep injection from a thermionic cathode.

Sets up user-specified injection for warpX.

Parameters

  • emitter (mewarpx.emission.Emitter) – Emitter object that will specify positions and velocities of particles to inject.

  • species (mewarpx.mespecies.Species) – A premade species. Note only electrons will actually give physically meaningful weight calculations.

  • npart_per_cellstep (int) – Number of macroparticles to inject per cell on the cathode surface per timestep

  • T (float) – Cathode temperature (K). Uses emitter T if not specified.

  • WF (float) – Cathode work function (eV). Uses WF of the conductor associated with the emitter if not specified.

  • A (float) – Coefficient of emission in Amp/m^2/K^2. Default is the theoretical max, approximately 1.2e6.

  • use_Schottky (bool) – Flag specifying whether or not to augment the emission current via field-dependent particle weights. Defaults to True.

  • Schottky_factor (float) – A prefactor on Schottky enhancement to simulate “anomalous Schottky enhancement” if greater than 1. Default 1.0.

  • allow_poisson (bool) – If True and < npart_per_cellstep electrons would be injected per cell, inject whole electrons with a Poisson distribution. If False, inject fractions of electrons. Default False.

  • wfac (float) – Constant factor applied to variable particle weights, which changes the actual injection weight from the physically calculated quantity. Currently used only for testing, or for e.g. artificially lowering weight of trace particles.

  • name (str or None) – Injector name for diagnostics. Constructed from speciesname if not given.

  • profile_decorator (decorator) – A decorator used to profile the injection methods and related functions.

  • unique_particles (bool) – Whether WarpX will keep all particles given it from every processor (True) or keep only a fraction of particles based on processor count (False). Default True.

inject_particles()[source]

Perform the actual injection!

class mewarpx.emission.UniformDistributionVolumeEmitter(T, xmin=None, xmax=None, ymin=None, ymax=None, zmin=None, zmax=None, rmin=None, rmax=None)[source]

Bases: VolumeEmitter

Inject particles uniformly throughout a given volume at a specified temperature.

Initialize emitter boundaries. A rectangular or cylindrical emitter volume is supported. If x & y boundaries are specified the r boundaries will be ignored and vice versa. If both x & y and r boundaries are specified an AttributeError will be raised. If no boundaries are given the simulation geometry and boundaries will be used.

Parameters

  • T (float) – Emitter temperature in Kelvin. Determines particle velocity distribution.

  • x/y/z/rmin (float) – Lower boundary of the volume.

  • x/y/z/rmax (float) – Upper boundary of the volume.

class mewarpx.emission.VolumeEmitter(T, xmin=None, xmax=None, ymin=None, ymax=None, zmin=None, zmax=None, rmin=None, rmax=None)[source]

Bases: BaseEmitter

Parent class for volumetric particle injection coordinates.

  • volume gives the spatial volume in m^3

  • _get_x_coords() implements the subclass-specific particle injection logic

Initialize emitter boundaries. A rectangular or cylindrical emitter volume is supported. If x & y boundaries are specified the r boundaries will be ignored and vice versa. If both x & y and r boundaries are specified an AttributeError will be raised. If no boundaries are given the simulation geometry and boundaries will be used.

Parameters

  • T (float) – Emitter temperature in Kelvin. Determines particle velocity distribution.

  • x/y/z/rmin (float) – Lower boundary of the volume.

  • x/y/z/rmax (float) – Upper boundary of the volume.

geoms = ['Z', 'XZ', 'RZ', 'XYZ']
getvoltage()[source]

Ideally this is probably the local potential, but default to 0.

getvoltage_e()[source]

Ideally this is probably the local potential, but default to 0.

volume = 0
class mewarpx.emission.XGaussZSinDistributionVolumeEmitter(x_sigma, *args, **kwargs)[source]

Bases: VolumeEmitter

Vary density in z as a half-period sin wave, and density in x as a Gaussian.

Initialize emitter boundaries. A rectangular or cylindrical emitter volume is supported. If x & y boundaries are specified the r boundaries will be ignored and vice versa. If both x & y and r boundaries are specified an AttributeError will be raised. If no boundaries are given the simulation geometry and boundaries will be used.

Parameters

  • T (float) – Emitter temperature in Kelvin. Determines particle velocity distribution.

  • x/y/z/rmin (float) – Lower boundary of the volume.

  • x/y/z/rmax (float) – Upper boundary of the volume.

geoms = ['XZ']
class mewarpx.emission.XPlaneEmitter(conductor, T=None, x=None, ymin=None, ymax=None, zmin=None, zmax=None, transverse_fac=1.0, xdir=1, **kwargs)[source]

Bases: Emitter

Injection for a planar cathode emitting from the simulation side.

Initialize an emitter for a planar cathode.

Parameters

  • conductor (mewarpx.assemblies.Assembly) – Conductor object, used to obtain work function and z coordinate/direction.

  • T (float) – Temperature in Kelvin for the emitter; determines velocities. If not specified the temperature of the conductor will be used.

  • x (float) – Position of the emitter along the x axis. Default conductor.x if it exists otherwise conductor.xmin/max depending on xdir. If none of those attributes exist an error will be raised if x is not specified.

  • ymin (float) – Minimum position of the rectangular emitter along y. Default conductor.ymin if it exists otherwise mwxrun.ymin.

  • ymax (float) – Maximum position of the rectangular emitter along y. Default conductor.ymax if it exists otherwise mwxrun.ymax.

  • zmin (float) – Minimum position of the rectangular emitter along z. Default conductor.zmin if it exists otherwise mwxrun.zmin.

  • zmax (float) – Maximum position of the rectangular emitter along z. Default conductor.zmax if it exists otherwise mwxrun.zmax.

  • transverse_fac (float) – Scale the transverse energy distribution by this factor. Default 1. See mewarpx.utils_store.util.get_velocities() for details.

  • xdir (int) – 1 to emit in +x, -1 to emit in -x.

  • kwargs (dict) – Any other keyword arguments supported by the parent Emitter constructor (such as “emission_type”).

geoms = ['XZ', 'XYZ']
get_normals(x, y, z)[source]

Calculate local surface normal at specified coordinates.

Parameters

  • x (np.ndarray) – x-coordinates of emitted particles (in meters).

  • y (np.ndarray) – y-coordinates of emitted particles (in meters).

  • z (np.ndarray) – z-coordinates of emitted particles (in meters).

Returns

nx3 array containing the outward surface

normal vector at each particle location.

Return type

normals (np.ndarray)

class mewarpx.emission.ZCylinderEmitter(conductor, T=None, zmin=None, zmax=None, rdir=1, transverse_fac=1.0, **kwargs)[source]

Bases: Emitter

This injects over the side faces of a cylinder oriented along z.

Initialize a 3D cylindrical emitter oriented along the z-axis.

Parameters

  • conductor (mewarpx.assemblies.Assembly) – Conductor object, used to obtain work function, coordinates and possibly temperature.

  • T (float) – Temperature in Kelvin for the emitter; determines velocities. If not specified the temperature of the conductor will be used.

  • zmin (float) – Lower z-coordinate for emitting surface. Default conductor.zmin if it exists otherwise mwxrun.zmin.

  • zmax (float) – Upper z-coordinate for emitting surface. Default conductor.zmax if it exists otherwise mwxrun.zmax.

  • rdir (float) – 1 for emitting outward of the cylinder (will use r_outer attribute of the conductor for the emitting surface), -1 for emitting inward towards r = 0 (will use r_inner attribute of the conductor for the emitting surface). Default 1.

  • transverse_fac (float) – Scale the transverse energy distribution by this factor. Default 1. See mewarpx.utils_store.util.get_velocities() for details.

  • kwargs (dict) – Any other keyword arguments supported by the parent Emitter constructor (such as “emission_type”).

Notes

The center of the cylinder is always x = y = 0 at present.

geoms = ['RZ', 'XYZ']
get_normals(x, y, z)[source]

Calculate local surface normal at specified coordinates.

Parameters

  • x (np.ndarray) – x-coordinates of emitted particles (in meters).

  • y (np.ndarray) – y-coordinates of emitted particles (in meters).

  • z (np.ndarray) – z-coordinates of emitted particles (in meters).

Returns

nx3 array containing the outward surface

normal vector at each particle location.

Return type

normals (np.ndarray)

class mewarpx.emission.ZDiscEmitter(conductor, T=None, inner_emission_radius=None, outer_emission_radius=None, transverse_fac=1.0, **kwargs)[source]

Bases: Emitter

This injects over an x-y disc rather than a rectangle.

Initialize an emitter for a disc (circular) cathode.

Parameters

  • conductor (mewarpx.assemblies.Assembly) – Conductor object, used to obtain work function and z coordinate/direction.

  • T (float) – Temperature in Kelvin for the emitter; determines velocities. If not specified the temperature of the conductor will be used.

  • inner_emission_radius (float) – Inner radius of the disc (in meters) for particles to be emitted from. Default mwxrun.rmin.

  • outer_emission_radius (float) – Outer radius of the disc (in meters) for particles to be emitted from. Default mwxrun.rmax.

  • transverse_fac (float) – Scale the transverse energy distribution by this factor. Default 1. See mewarpx.utils_store.util.get_velocities() for details.

  • kwargs (dict) – Any other keyword arguments supported by the parent Emitter constructor (such as “emission_type”).

Notes

The center of the disc is always x = y = 0 at present.

geoms = ['RZ']
get_normals(x, y, z)[source]

Calculate local surface normal at specified coordinates.

Parameters

  • x (np.ndarray) – x-coordinates of emitted particles (in meters).

  • y (np.ndarray) – y-coordinates of emitted particles (in meters).

  • z (np.ndarray) – z-coordinates of emitted particles (in meters).

Returns

nx3 array containing the outward surface

normal vector at each particle location.

Return type

normals (np.ndarray)

class mewarpx.emission.ZPlaneEmitter(conductor, T=None, xmin=None, xmax=None, ymin=None, ymax=None, transverse_fac=1.0, **kwargs)[source]

Bases: Emitter

This is the standard injection for a planar cathode.

Initialize an emitter for a planar cathode.

Parameters

  • conductor (mewarpx.assemblies.Assembly) – Conductor object, used to obtain work function and z coordinate/direction.

  • T (float) – Temperature in Kelvin for the emitter; determines velocities. If not specified the temperature of the conductor will be used.

  • xmin (float) – Minimum position of the rectangular emitter along x. Default mwxrun.xmin.

  • xmax (float) – Maximum position of the rectangular emitter along x. Default mwxrun.xmax.

  • ymin (float) – Minimum position of the rectangular emitter along y. Default mwxrun.ymin.

  • ymax (float) – Maximum position of the rectangular emitter along y. Default mwxrun.ymax.

  • transverse_fac (float) – Scale the transverse energy distribution by this factor. Default 1. See mewarpx.utils_store.util.get_velocities() for details.

  • kwargs (dict) – Any other keyword arguments supported by the parent Emitter constructor (such as “emission_type”).

geoms = ['Z', 'XZ', 'XYZ']
get_normals(x, y, z)[source]

Calculate local surface normal at specified coordinates.

Parameters

  • x (np.ndarray) – x-coordinates of emitted particles (in meters).

  • y (np.ndarray) – y-coordinates of emitted particles (in meters).

  • z (np.ndarray) – z-coordinates of emitted particles (in meters).

Returns

nx3 array containing the outward surface

normal vector at each particle location.

Return type

normals (np.ndarray)

class mewarpx.emission.ZPlanePatchSet(conductor, T=None, xmin=None, xmax=None, ymin=None, ymax=None, transverse_fac=1.0, **kwargs)[source]

Bases: ZPlaneEmitter

Emitter for a set of single WF patches. This is meant to be used by the ZPlanePatchyEmitter, not directly.

Initialize an emitter for a planar cathode.

Parameters

  • conductor (mewarpx.assemblies.Assembly) – Conductor object, used to obtain work function and z coordinate/direction.

  • T (float) – Temperature in Kelvin for the emitter; determines velocities. If not specified the temperature of the conductor will be used.

  • xmin (float) – Minimum position of the rectangular emitter along x. Default mwxrun.xmin.

  • xmax (float) – Maximum position of the rectangular emitter along x. Default mwxrun.xmax.

  • ymin (float) – Minimum position of the rectangular emitter along y. Default mwxrun.ymin.

  • ymax (float) – Maximum position of the rectangular emitter along y. Default mwxrun.ymax.

  • transverse_fac (float) – Scale the transverse energy distribution by this factor. Default 1. See mewarpx.utils_store.util.get_velocities() for details.

  • kwargs (dict) – Any other keyword arguments supported by the parent Emitter constructor (such as “emission_type”).

class mewarpx.emission.ZPlanePatchyEmitter(patchy_cathode, transverse_fac=1.0, **kwargs)[source]

Bases: object

Injection for a patchy cathode.

Initialize an emitter for a planar patchy cathode.

Parameters

  • patchy_cathode (mewarpx.assemblies.PatchyCathode) – Patchy cathode object, used to obtain work functions, patch size and z coordinate/direction.

  • transverse_fac (float) – Scale the transverse energy distribution by this factor. Default 1. See mewarpx.utils_store.util.get_velocities() for details.

  • kwargs (dict) – Any other keyword arguments supported by the Emitter constructor (such as “emission_type”).

geoms = ['XZ']
class mewarpx.emission.ZSinDistributionVolumeEmitter(T, xmin=None, xmax=None, ymin=None, ymax=None, zmin=None, zmax=None, rmin=None, rmax=None)[source]

Bases: VolumeEmitter

Vary density in z as a half-period sin wave.

Initialize emitter boundaries. A rectangular or cylindrical emitter volume is supported. If x & y boundaries are specified the r boundaries will be ignored and vice versa. If both x & y and r boundaries are specified an AttributeError will be raised. If no boundaries are given the simulation geometry and boundaries will be used.

Parameters

  • T (float) – Emitter temperature in Kelvin. Determines particle velocity distribution.

  • x/y/z/rmin (float) – Lower boundary of the volume.

  • x/y/z/rmax (float) – Upper boundary of the volume.

mewarpx.mcc_wrapper module

class mewarpx.mcc_wrapper.MCC(electron_species, ion_species, T_INERT, P_INERT=None, N_INERT=None, scraper=None, **kwargs)[source]

Bases: Injector

Wrapper used to initialize Monte Carlo collision parameters

Initialize MCC parameters.

Parameters

  • electron_species (picmi.Species) – Species that will be producing the ions via impact ionization. This will normally be electrons.

  • ion_species (picmi.Species) – Ion species generated from ionization events. Charge state should be specified during Species construction. Also used to obtain the neutral mass.

  • T_INERT (float) – Temperature for injected ions in Kelvin.

  • P_INERT (float) – Pressure of the neutral “target” for impact ionization, in Torr. Assumed to be such that the density is much larger than both the electron and ion densities, so that the neutral dynamics can be ignored. Cannot be specified if N_INERT is specified.

  • N_INERT (float) – Neutral gas density in m^-3. Cannot be specified if P_INERT is specified.

  • scraper (pywarpx.ParticleScraper) – The particle scraper is instructed to save pid’s for number of MCC events.

  • included (**kwargs that can be) –

  • exclude_collisions (list) – A list of collision types to exclude.

mewarpx.mespecies module

File to hold a child class of picmi.Species to allow us to add extra attributes and functionality to species.

mewarpx.mwxrun module

This facilitates a central place to grab lots of simulation information for our use.

SETUP order:

  • Import other mewarpx modules

  • Use from mewarpx.mwxrun import mwxrun to import the class holding all the simulation information, defined here.

  • Set up PICMI things, referring to mwxrun’s picmi.Simulation object, mwxrun.simulation. Add PICMI species to the PICMI Simulation.

  • Call this class’s init_run:

    mwxrun.mwxrun.init_run()

  • Initialize any other mewarpx objects

class mewarpx.mwxrun.MEWarpXRun[source]

Bases: object

Hold base information and wrappers for the simulation. This should be a singleton object.

This also does the initialization steps, using init_run to enforce an initialization order.

calc_Schottky_weight(species_name, pre_fac)[source]

Function to calculate weight for field-enhanced Schottky emission.

Parameters

  • species_name (str) – The name of the species for which Schottky enhancement will be calculated.

  • pre_fac (float) – Exponent pre-factor in the Schottky enhancement calculation -> sqrt(e / 4*pi*eps0) / (kT)

eval_expression_t(expr, t=None)[source]

Function to evaluate an expression that depends on time, at the current simulation time using the WarpX parser.

Parameters

  • expr (str or float) – Expression to evaluate.

  • t (float) – Optional value of t at which to evaluate the function, if not supplied the current simulation time will be used.

Returns

(float) Value of the expression at the current simulation time.

get_domain_area()[source]

Return float of simulation domain area in X & Y directions or R depending on geometry. Used to get the surface area over which current is emitted or absorbed.

get_dt()[source]

Return the timestep.

get_gathered_phi_grid(include_ghosts=False)[source]

Get the full phi on the grid.

Parameters

include_ghosts (bool) – Whether or not to include ghost cells.

Returns

A numpy array with phi on the full domain.

get_gathered_rho_grid(species_name=None, include_ghosts=False)[source]

Get the full rho on the grid on the root processor.

Parameters

  • species_name (str or None) – If specified the charge density for the specific species will be returned (deposited on the grid). If None, the current state of rho_fp will be returned.

  • include_ghosts (bool) – Whether or not to include ghost cells.

Returns

A numpy array with rho on the full domain.

get_it()[source]

Return the current integer iteration number.

get_npart()[source]

Get total number of particles in simulation, across all processors.

get_npart_species_dict()[source]

Get total number of particles in simulation per species, across all processors.

get_t()[source]

Return the simulation time.

init_grid(lower_bound, upper_bound, number_of_cells, use_rz=False, **kwargs)[source]

Function to set up the simulation grid.

Parameters

  • lower_bound (list) – Minimum coordinates for all direction; length of list has to equal number of dimensions.

  • upper_bound (list) – Maximum coordinates for all direction; length of list has to equal number of dimensions.

  • number_of_cells (list) – Number of grid cells in each direction.

  • use_rz (bool) – If True, cylindrical coordinates will be used.

  • kwargs (dict) –

    Dictionary containing extra arguments. These can include: - bc_fields_x/y/z/r_min/max: field boundary condition

    settings (can be ‘periodic’, ‘dirichlet’ or ‘none’).

    • bc_particles_x/y/z/r_min/max: particle boundary condition settings (can be ‘periodic’, ‘absorbing’ or ‘reflecting’).

    • min_tiles: the minimum number of tiles. See function _set_max_grid_size() below for details.

init_run(restart=None, checkpoint_dir='diags', checkpoint_prefix='checkpoint', additional_steps=None)[source]
init_timestep(DT=None, CFL_factor=None, V_grid=5)[source]

Calculate timestep size based on grid data and CFL parameter

Parameters

  • DT (float) – The dt of each step of the simulation, if not given it will be calculated.

  • CFL_factor (float) – Multiplier to determine the actual timestep given the CFL ratio. eg. dt = CFL_factor * CFL_ratio.

  • V_grid (float) – The vaccum bias of highest-voltage grid relative to the cathode V. If not defined a value of 5 V is used, which is a safe value for finding vmax in the case that the electron velocities are only set by their temperature.

move_particles_between_species(src_species_name, dst_species_name)[source]

Function to move particles from one particle container to another. Particles will be removed from the source particle container.

Parameters

  • src_species_name (str) – The source species name

  • dst_species_name (str) – The destination species name

set_phi_grid(phi_data)[source]

Sets phi on the grid to input phi data.

Parameters

phi_data (numpy array) – Phi values on the grid.

mewarpx.mwxrun.exit_handler()[source]

mewarpx.poisson_pseudo_1d module

mewarpx.runinfo module

mewarpx.sim_control module

Control code used to terminate simulation based on a set of user defined criteria

class mewarpx.sim_control.SimControl(total_steps, diag_steps, criteria=None, checkpoint=False, dump_period=None, **kwargs)[source]

Bases: WarpXDiagnostic

The main simulation driving class. It evaluates whether to continue or terminate the simulation based on a set of user defined criteria.

Generate and install functions to perform after a step #.

Parameters

  • total_steps (int) – Total number of steps to perform in the simulation, when step == total_steps check_criteria returns False

  • diag_steps (int) – Steps between diagnostic output

  • criteria (list) – list of user defined functions or list of user defined tuples(function, kwargs) that each return a True or False value

  • checkpoint (bool) – Whether or not simulation checkpoints should be made

  • dump_period (int) – Checkpoints will be created every diag_steps*dump_period steps. If the dump_period is not given, checkpoints will only be created when the simulation ends ( including interrupts due to a TERMINATE signal)

add_checker(criterion)[source]

Install a single function to check.

Parameters

criterion (func or tuple) – Either a function or a tuple of (func, kwargs_dict) where the kwargs_dict will be passed to the func.

check_criteria()[source]

Sends an interrupt signal to the current process if a termination criteria is satisfied.

initialize_criteria(criteria_list)[source]

Install the full initial list of criteria.

run()[source]

Executes the WarpX loop.

set_write_func(func)[source]

Sets a function for writing to results.txt file.

Parameters

  • func (function) – Returns a string that will be written to the

  • file (results.txt) –

trigger_checkpoint()[source]

Helper function to trigger the checkpoint diagnostic to write a checkpoint.

write_results()[source]

Create results.txt file, and write to it if write_func is set. The file signifies that the simulation ran to completion.

Module contents

mewarpx package