molecule

plasmapy.particles.particle_class.molecule(symbol: str, Z: Integral | None = None) → Particle | CustomParticle[source]

Parse a molecule symbol into a CustomParticle or Particle.

Parameters:

  • symbol (str) – Symbol of the molecule to be parsed. This argument should be a string representing the chemical formula where the subscript numbers are not given as subscripts, followed by charge information. For example, CO2 can be represented as "CO2" and CO+ can be represented as "CO 1+", "CO +1", or "CO+".

  • Z (integer, optional) – The charge number of the molecule.

Returns:

A Particle object if the input could be parsed as such, or a CustomParticle with the provided symbol, charge, and a mass corresponding to the sum of the molecule elements.

Return type:

Particle or CustomParticle

Raises:

InvalidParticleError – If symbol couldn’t be parsed.

Warns:

ParticleWarning – If the charge is given both as an argument and in the symbol.

Examples

>>> from plasmapy.particles import molecule
>>> molecule("I2")
CustomParticle(mass=4.214...e-25 kg, charge=0.0 C, symbol=I2)

Charge information is given either within the symbol or as a second parameter.

>>> molecule("I2+")
CustomParticle(mass=4.214...e-25 kg, charge=1.602...e-19 C, symbol=I2 1+)

>>> molecule("I2", 1)
CustomParticle(mass=4.214...e-25 kg, charge=1.602...e-19 C, symbol=I2 1+)

Inputs that can be interpreted as Particle instances are returned as such.

>>> molecule("Xe")
Particle("Xe")

The given symbol is preserved in the CustomParticle instance. This permits us to differentiate between isomers:

>>> molecule("CH4O2") == molecule("CH3OOH")
False