CustomParticle

class plasmapy.particles.particle_class.CustomParticle(mass: Quantity = None, charge: Quantity = None, symbol: str | None = None, *, Z: float | None = None)[source]

Bases: AbstractPhysicalParticle

A class to represent custom particles.

Example use cases for this class include representing an average ion in a multi-component plasma, molecules, or dust grains.

Parameters:
  • mass (Quantity, optional) – The mass of the custom particle in units of mass. Defaults to nan kg.

  • charge (Quantity | float, optional) – The electric charge of the custom particle. If provided as a Quantity, then it must be in units of electric charge. Defaults to nan C.

  • Z (float, keyword-only, optional) – The charge number, which is equal to the ratio of the charge to the elementary charge.

  • symbol (str, optional) – The symbol to be assigned to the custom particle.

Raises:

InvalidParticleError – If the charge or mass provided is invalid so that the custom particle cannot be created.

Notes

If the charge or mass is not specified, then the corresponding value will be set to nan in the appropriate units.

Examples

>>> import astropy.units as u
>>> from plasmapy.particles import CustomParticle
>>> custom_particle = CustomParticle(
...     mass=1.2e-26 * u.kg,
...     charge=9.2e-19 * u.C,
... )
>>> custom_particle.mass
<Quantity 1.2e-26 kg>
>>> custom_particle.charge
<Quantity 9.2e-19 C>
>>> average_particle = CustomParticle(
...     mass=1.5e-26 * u.kg,
...     Z=-1.5,
...     symbol="Ξ",
... )
>>> average_particle.mass
<Quantity 1.5e-26 kg>
>>> average_particle.charge
<Quantity -2.40326...e-19 C>
>>> average_particle.symbol
'Ξ'

Attributes Summary

categories

Categories for the CustomParticle.

charge

The electric charge of the CustomParticle in coulombs.

charge_number

The ratio of the charge to the elementary charge.

json_dict

A json friendly dictionary representation of the CustomParticle.

mass

The mass of the CustomParticle.

mass_energy

The mass energy of the CustomParticle.

symbol

The symbol assigned to the CustomParticle.

Methods Summary

is_category(*category_tuple[, require, ...])

Determine if the particle meets categorization criteria.

json_dump(fp, **kwargs)

Write the particle's json_dict to the fp file object using json.dump.

json_dumps(**kwargs)

Serialize the particle's json_dict into a JSON formatted str using json.dumps.

Attributes Documentation

categories

Categories for the CustomParticle.

charge

The electric charge of the CustomParticle in coulombs.

charge_number

The ratio of the charge to the elementary charge.

json_dict

A json friendly dictionary representation of the CustomParticle.

See json_dict for more details.

Examples

>>> custom_particle = CustomParticle(
...     mass=5.12 * u.kg,
...     charge=6.2 * u.C,
...     symbol="ξ",
... )
>>> custom_particle.json_dict
{'plasmapy_particle': {'type': 'CustomParticle',
    'module': 'plasmapy.particles.particle_class',
    'date_created': '...',
    '__init__': {'args': (), 'kwargs': {'mass': '5.12 kg', 'charge': '6.2 C',
    'charge_number': '3.869735626...e+19', 'symbol': 'ξ'}}}}
>>> custom_particle = CustomParticle(mass=1.5e-26 * u.kg)
>>> custom_particle.json_dict
{'plasmapy_particle': {'type': 'CustomParticle',
    'module': 'plasmapy.particles.particle_class',
    'date_created': '...',
    '__init__': {'args': (), 'kwargs': {'mass': '1.5e-26 kg',
    'charge': 'nan C', 'charge_number': 'nan',
    'symbol': 'CustomParticle(mass=1.5e-26 kg, charge=nan C)'}}}}
mass

The mass of the CustomParticle.

mass_energy

The mass energy of the CustomParticle.

Examples

>>> import astropy.units as u
>>> custom_particle = CustomParticle(mass=2e-25 * u.kg, charge=0 * u.C)
>>> custom_particle.mass_energy.to("GeV")
<Quantity 112.19177208 GeV>
symbol

The symbol assigned to the CustomParticle.

If no symbol was defined, then return the value given by repr.

Methods Documentation

is_category(*category_tuple, require: str | Iterable[str] | None = None, any_of: str | Iterable[str] | None = None, exclude: str | Iterable[str] | None = None) bool

Determine if the particle meets categorization criteria.

Return True if the particle is consistent with the provided categories, and False otherwise.

Parameters:
  • *category_tuple – Required categories in the form of one or more str objects or an iterable.

  • require (str or iterable of str, keyword-only, optional) – One or more particle categories. This method will return False if the particle does not belong to all of these categories.

  • any_of (str or iterable of str, keyword-only, optional) – One or more particle categories. This method will return False if the particle does not belong to at least one of these categories.

  • exclude (str or iterable of str, keyword-only, optional) – One or more particle categories. This method will return False if the particle belongs to any of these categories.

See also

valid_categories

A set containing all valid particle categories.

Notes

Valid particle categories are given in valid_categories and include: "actinide", "alkali metal", "alkaline earth metal", "antibaryon", "antilepton", "antimatter", "antineutrino", "baryon", "boson", "charged", "custom", "electron", "element", "fermion", "halogen", "ion", "isotope", "lanthanide", "lepton", "matter", "metal", "metalloid", "neutrino", "neutron", "noble gas", "nonmetal", "positron", "post-transition metal", "proton", "stable", "transition metal", "uncharged", and "unstable".

Examples

Required categories may be entered as positional arguments, including as a list, set, or tuple of required categories.

>>> electron = Particle("e-")
>>> electron.is_category("lepton")
True
>>> electron.is_category("lepton", "baryon")
False
>>> electron.is_category(["fermion", "matter"])
True

Required arguments may also be provided using the require keyword argument.

>>> electron.is_category(require="lepton")
True
>>> electron.is_category(require=["lepton", "baryon"])
False

This method will return False if the particle does not belong to at least one of the categories provided with the any_of keyword argument.

>>> electron.is_category(any_of=["lepton", "baryon"])
True
>>> electron.is_category(any_of=("noble gas", "lanthanide", "halogen"))
False

This method will return False if the particle belongs to any of the categories provided in the exclude keyword argument.

>>> electron.is_category(exclude="baryon")
True
>>> electron.is_category(exclude={"lepton", "baryon"})
False

The require, any_of, and exclude keywords may be combined. If the particle matches all of the provided criteria, then this method will return True.

>>> electron.is_category(
...     require="fermion",
...     any_of={"lepton", "baryon"},
...     exclude="charged",
... )
False
json_dump(fp, **kwargs: dict[str, Any]) None

Write the particle’s json_dict to the fp file object using json.dump.

Parameters:
json_dumps(**kwargs: object) str

Serialize the particle’s json_dict into a JSON formatted str using json.dumps.

Parameters:

**kwargs – Any keyword accepted by json.dumps.

Returns:

JSON formatted str.

Return type:

str