ParticleMethods Library Functions

ParticleMethods

Data structures for particles and particle lists: Particle and ParticleList, with named access to parts of the state and to parameters.

ChargeWeights{T} <: AbstractMatrix{T}

The charge-weighted weights q_i · w_i of the particles in a ParticleList, as a lazy 1 × np matrix whose [1, i] element is the charge of particle i times its weight. Returned by chargeweights.

Particle(state; variables = NamedTuple(), parameters = NamedTuple())
Particle(DT, len; variables = NamedTuple(), parameters = NamedTuple())

A particle with the state vector state, or a zero state of element type DT and length len.

variables maps names to indices or index ranges into state, and parameters maps names to values. Each name is a property of the particle: p.x is a view into state for a variable x, and the stored value for a parameter. The names must not repeat each other or the field names state, views and params.

Example

p = Particle(Float64, 7; variables = (x = 1:3, v = 4:6, w = 7))
p.x    # view(p.state, 1:3)

ParticleList(list::AbstractMatrix; variables = NamedTuple(), parameters = NamedTuple(),
             species = [Species(:default, 1, 1)], speciesindex = nothing)
ParticleList(DT, np, nd; variables = NamedTuple(), parameters = NamedTuple(),
             species = [Species(:default, 1, 1)], speciesindex = nothing)
ParticleList(x, v, w; parameters = NamedTuple(), species = [Species(:default, 1, 1)],
             speciesindex = nothing)
ParticleList(h5::H5DataStore, path = "/")
ParticleList(fpath::AbstractString, path = "/")

A list of particles, stored as the columns of the matrix list. Each column is the state of one particle, and pl[i] is that particle as a Particle.

variables maps names to row indices or row ranges of list, and parameters maps names to values. Each name is a property of the list: pl.x is a view into the rows of a variable x for all particles, and the stored value for a parameter. The names must not repeat each other or the field names list, views, params, particles, variables, indices, species and speciesindex.

species is the table of particle species, each a Species with a charge and a mass, and speciesindex gives the species of each particle as an index into that table. The table is converted to the element type of list, and the index is copied. A list built without species holds one species with charge and mass one, so chargeweights(pl)[1, i] is the weight w_i of particle i. A list with more than one species needs an explicit speciesindex of length np, with every index in 1:length(species).

The second form makes a zero list of element type DT with np particles of nd components. The third form stacks positions x, velocities v and weights w, and defines the variables x, v, z (positions and velocities) and w. The last two forms read a list that h5save wrote, from a group path of an HDF5 file or from the file at fpath.

Species(name::Symbol, charge, mass)
Species{T}(name::Symbol, charge, mass)

A particle species: a name, a charge q and a mass m, shared by every particle of that species. Species(name, charge, mass) promotes the charge and the mass to their common type, and Species{T}(s::Species) converts an existing species to the element type T of a ParticleList.

The mass must be positive: a mass that is not, NaN included, throws an ArgumentError, and the conversion to T checks again, so a mass that rounds to zero in T throws too. The charge may be zero.

Example

s = Species(:e, -1.0, 0.5)
s.charge   # -1.0
s.mass     # 0.5

charge(pl::ParticleList, i::Integer)

Return the charge of particle i in pl, the charge of its Species.

charge(s::Species)

Return the charge q of the species s.

chargeweights(pl::ParticleList)

Return the charge-weighted weights of the particles in pl as a lazy 1 × np matrix, whose [1, i] element is charge(pl, i) * w_i, the weight of particle i. This is the weight a charge deposit reads, so a deposit that weights each particle by its charge changes one argument and no signature.

It throws an ArgumentError when pl has no variable w, or when w spans more than one row.

eachparticle(pl::ParticleList)

Return the vector of the Particles in pl. Each particle is a view into a column of pl.list.

mass(pl::ParticleList, i::Integer)

Return the mass of particle i in pl, the mass of its Species.

mass(s::Species)

Return the mass m of the species s.

species(pl::ParticleList, i::Integer)

Return the Species of particle i in pl, that is pl.species[pl.speciesindex[i]].