.. currentmodule:: plasmapy
.. glossary::
:sorted:
alias
aliases
An abbreviated version of a commonly used function. For
example, `~plasmapy.formulary.speeds.va_` is an alias for
`~plasmapy.formulary.speeds.Alfven_speed`. Aliases are
named with a trailing underscore.
For further details, please refer to the :ref:`contributor guide's
section on aliases <aliases>`.
args
An abbreviation for `positional arguments`_.
atom-like
A |particle-like| `object` is **atom-like** if it is or could be
cast into:
* A |Particle| representing an element, isotope, or ionic level; or
* A |ParticleList| including only elements, isotopes, or ionic levels.
For example, ``"p+"``, ``"He-4"``, ``"deuterium"``, ``"O 0+"``,
``Particle("Fe-56 16+)"``, ``["He-4 1+", "He-4 2+"]``, and
integers representing atomic numbers are all atom-like.
Examples of objects that are |particle-like| but *not* atom-like
include ``"neutron"``, ``"e-"``, and ``["e-", "e+"]``.
Additionally, ``["He-4", "e-"]`` is not atom-like because this
`list` contains an item that is not atom-like.
Please refer to the glossary entry for |particle-like| for a full
description of valid representations of elements, isotopes, and
ions.
-like
Used to indicate an `object` of that type or that can instantiate
that type. For example, ``"He 2+"`` is |particle-like| because it
can be used to instantiate |Particle|.
charge number
The electrical charge of a particle in units of the elementary
charge. The charge number of an ion or neutral particle is usually
denoted as ``Z``.
fit-function
fit-functions
Any instance of a subclass of
`~plasmapy.analysis.fit_functions.AbstractFitFunction`. Also see
module `~plasmapy.analysis.fit_functions`.
force-free
In plasma physics, a **force-free magnetic field** is a magnetic
field where the Lorentz force is zero, meaning the magnetic
pressure greatly exceeds the plasma pressure, allowing
non-magnetic forces to be neglected. This condition is often
approximated in the Sun's corona.
For more details, visit the `Wikipedia page <https://en.wikipedia.org/wiki/Force-free_magnetic_field>`_.
integration test
An **integration test** verifies that multiple software
components work together as intended.
Compared to a :term:`unit test`, an integration test is typically
harder to write, slower to run, more difficult to maintain, and
less useful at pinpointing the specific cause of a problem.
However, integration tests are able to find problems that unit
tests cannot. In particular, integration tests are able to find
problems at the interfaces between different modules. On average,
each integration test covers more lines of code than each related
:term:`unit test`. Because unit tests and integration tests
complement each other, both are important constituents of a test
suite.
keyword-only
An |argument| or |parameter| is *keyword-only* when the |argument|
must be provided with the name of the corresponding |parameter|.
If ``z`` is a keyword-only |parameter| to ``f(z)``, then the
|argument| ``2`` can be provided as ``f(z=2)`` but not ``f(2)``.
kwargs
An abbreviation for `keyword arguments`_.
lite-function
lite-functions
An optimized version of an existing `plasmapy` function intended
for applications where computational efficiency is most important.
While most `~plasmapy.formulary` functions accept |Quantity|
objects created using `astropy.units`, lite-functions accept
numbers and |array_like| inputs that are implicitly assumed to be
in SI units. The name of a lite-function ends with ``_lite``. A
lite-function can be accessed as the ``lite`` attribute of the
corresponding regular function.
.. caution::
Unlike most `~plasmapy.formulary` functions, no validations are
performed on the arguments provided to a lite-function for the
sake of computational efficiency. When using lite-functions, it
is vital to double-check your implementation!
For further details, please refer to the :ref:`contributor guide's
section on lite-functions <lite-functions>`.
particle-like
An `object` is *particle-like* if it is a |Particle| or
|CustomParticle|, or can be cast into one.
An **element** may be represented by a string containing the
atomic symbol (case-sensitive), the name of the element, or an
integer representing the atomic number. The element iron can be
represented as ``"Fe"``, ``"iron"``, or ``26``.
An **isotope** may be represented by a string that contains an
atomic symbol or element name, followed by a hyphen and the mass
number (with no spaces in between). The isotope :sup:`56`\ Fe can
be represented as ``"Fe-56"``, or ``"iron-56"``. :sup:`2`\ H can
be represented by ``"D"`` or ``"deuterium"``, and :sup:`3`\ H can
be represented by ``"T"`` or ``"tritium"``.
An **ion** or **neutral atom** may be represented by a string that
contains a representation of an element or isotope, followed by
charge information which is typically an integer representing the
charge number and a plus or minus sign to indicate the electrical
charge. For example, a deuteron may be represented as ``"D 1+"``
and :sup:`56`\ Fe\ :sup:`1+` may be represented as ``"Fe-56 1+"``.
A **special particle** may be represented by a string that
contains the name of the particle (case insensitive) or a
standard symbol for it (case insensitive). A neutron can be
represented as ``"n"`` or ``"neutron"``; a proton can be
represented as ``"p+"``, ``"p"``, or ``"proton"``; and an electron
can be represented by ``"e-"``, ``"e"``, or ``"electron"``.
|DimensionlessParticle| instances are not particle-like because,
without normalization information, they do not uniquely identify a
physical particle.
For more complete details, refer to |ParticleLike|.
particle-list-like
An `object` is *particle-list-like* if it is a |ParticleList|, or
can be cast into one.
For more complete details, refer to |ParticleListLike|.
real number
Any numeric type that represents a real number. This could include
a `float`, `int`, a dimensionless |Quantity|, or any of the
`numpy.number` types. Note that if a PlasmaPy function expects a
dimensional |Quantity| and a real number is provided, then the
real number is often assumed to have the appropriate SI units.
temperature
Most functions in PlasmaPy accept temperature, :math:`T`, as a
`~astropy.units.Quantity` with units of temperature (e.g., kelvin)
or energy (e.g., electron-volts). A value for energy that is
provided will be divided by the Boltzmann constant, :math:`k_B`,
to be converted into units of temperature.
unit test
A **unit test** verifies a single unit of behavior, does it
quickly, and does it in isolation from other tests
:cite:p:`khorikov:2020`.
Unit tests are intended to provide fast feedback that help pinpoint
the locations of errors. Unit tests often abide by the following
pattern :cite:p:`osherove:2013`:
1. *Arrange*: gather inputs and get the system to the state in which
the test is expected to run.
2. *Act*: make the system under test undertake the operation that is
being tested.
3. *Assert*: verify that the actual outcome of the *act* phase matches
the expected outcome.
In a unit test for a function, the *arrange* phase involves
collecting or constructing the inputs for the function. The *act*
phase occurs when the function is called with those inputs. The
*assert* phase is when the value returned by the function is
compared to the expected result.