CustomParticle

class plasmapy.particles.particle_class.CustomParticle( mass: Annotated[Quantity, Unit('kg')] = None, charge: Annotated[Quantity, Unit('C')] = 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.

See also

Particle, DimensionlessParticle

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

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:

fp (file object) – Destination file object to write the JSON serialized json_dict.
**kwargs – Any keyword accepted by json.dump.

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