created intensity function (PlasmaPy#3032)

* created intensity function

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add changelog entry

* fix formatting

* fix units and formatting

* add tests for intensity function

* fix parameter for test_intensity_errors

* fix formatting

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix units in documentation

* Update src/plasmapy/formulary/laser.py

Co-authored-by: Nick Murphy <namurphy@users.noreply.github.com>

* Update src/plasmapy/formulary/laser.py

Co-authored-by: Nick Murphy <namurphy@users.noreply.github.com>

* Update src/plasmapy/formulary/laser.py

Co-authored-by: Nick Murphy <namurphy@users.noreply.github.com>

* Update src/plasmapy/formulary/laser.py

Co-authored-by: Nick Murphy <namurphy@users.noreply.github.com>

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Nick Murphy <namurphy@users.noreply.github.com>

Author: 3 people

changelog/3032.feature.rst

@@ -0,0 +1 @@
+Added the second function to `plasmapy.formulary.laser`, `~plasmapy.formulary.laser.intensity`, which calculates intensity from the electric field amplitude.

src/plasmapy/formulary/laser.py

@@ -8,8 +8,9 @@
 
 __all__ = [
     "electric_field_amplitude",
+    "intensity",
 ]
-__aliases__ = ["E0_"]
+__aliases__ = ["E0_", "I_"]
 
 import astropy.units as u
 import numpy as np
@@ -68,3 +69,53 @@ def electric_field_amplitude(
 
 E0_ = electric_field_amplitude
 """Alias to `~plasmapy.formulary.laser.electric_field_amplitude`."""
+
+
+@validate_quantities(
+    electric_field_amplitude={"can_be_negative": False},
+)
+def intensity(
+    electric_field_amplitude: u.Quantity[u.V / u.m],
+) -> u.Quantity[u.watt / u.m**2]:
+    r"""
+    Calculate the intensity :math:`I` of a laser from the
+    electric field amplitude :math:`E_0`.
+
+    The intensity of an electromagnetic plane wave in vacuum
+    is calculated using:
+
+    .. math::
+        I=\frac{1}{2} c ε_0 E_0^2,
+
+    where :math:`c` is the speed of light and
+    :math:`ε_0` is the permittivity of free space.
+
+    **Aliases:** `I_`
+
+    Parameters
+    ----------
+    electric_field_amplitude: `~astropy.units.Quantity`
+        Electric field amplitude of an electromagnetic plane wave
+        (convertible to V / m).
+
+    Returns
+    -------
+    Int : `~astropy.units.Quantity`
+        Intensity for the electric field amplitude provided.
+
+    Notes
+    -----
+    For details, see :cite:t:`ling:2016`\ .
+
+    Examples
+    --------
+    >>> import astropy.units as u
+    >>> intensity(0.8680211 * u.V / u.m)
+    <Quantity 0.001 W / m2>
+    """
+
+    return (1 / 2) * c * eps0 * electric_field_amplitude**2
+
+
+I_ = intensity
+"""Alias to `~plasmapy.formulary.laser.intensity`."""

tests/formulary/test_laser.py

@@ -5,7 +5,7 @@
 import pytest
 from astropy.tests.helper import assert_quantity_allclose
 
-from plasmapy.formulary.laser import E0_, electric_field_amplitude
+from plasmapy.formulary.laser import E0_, I_, electric_field_amplitude, intensity
 
 
 @pytest.mark.parametrize(
@@ -50,8 +50,47 @@ def test_electric_field_amplitude_warnings(intensity, expected_warning) -> None:
     ("alias", "parent"),
     [
         (E0_, electric_field_amplitude),
+        (I_, intensity),
     ],
 )
 def test_aliases(alias, parent) -> None:
     """Test all aliases defined in laser.py"""
     assert alias is parent
+
+
+@pytest.mark.parametrize(
+    ("electric_field_amplitude", "expected"),
+    [
+        (0.8680211 * u.V / u.m, 1e-3 * u.watt / u.m**2),
+        ([0.8680211, 0] * u.V / u.m, [1, 0] * u.milliWatt / u.m**2),
+        (np.nan * u.V / u.m, np.nan * u.watt / u.m**2),
+    ],
+)
+@pytest.mark.filterwarnings("ignore::astropy.units.UnitsWarning")
+def test_intensity(electric_field_amplitude, expected) -> None:
+    result = intensity(electric_field_amplitude=electric_field_amplitude)
+    assert_quantity_allclose(result, expected, rtol=1e-6, equal_nan=True, verbose=True)
+    assert result.unit == u.Watt / u.m**2
+
+
+@pytest.mark.parametrize(
+    ("electric_field_amplitude", "expected"),
+    [
+        (-5e4 * u.V / u.m, ValueError),
+        (1 * u.kg, u.UnitTypeError),
+    ],
+)
+def test_intensity_errors(electric_field_amplitude, expected) -> None:
+    with pytest.raises(expected):
+        intensity(electric_field_amplitude=electric_field_amplitude)
+
+
+@pytest.mark.parametrize(
+    ("electric_field_amplitude", "expected_warning"),
+    [
+        (5, u.UnitsWarning),
+    ],
+)
+def test_intensity_warnings(electric_field_amplitude, expected_warning) -> None:
+    with pytest.warns(expected_warning):
+        intensity(electric_field_amplitude=electric_field_amplitude)