Law: total energy of planet is negative kinetic energy (#867)

* Create law and test

* Fix title

* Fix documentation

symplyphysics/laws/gravity/radial_motion/total_energy_is_negative_average_kinetic_energy.py

@@ -0,0 +1,58 @@
+"""
+Total energy is negative average kinetic energy
+===============================================
+
+The total energy of an orbiting planet is equal to its negative kinetic energy averaged over time.
+
+**Conditions:**
+
+#. Works for elliptical (:math:`E < 0`) orbits.
+
+**Notes:**
+
+#. :code:`<A>` denotes the average of the quantity :code:`A`.
+"""
+
+from sympy import Eq
+from symplyphysics import (
+    units,
+    Quantity,
+    Symbol,
+    validate_input,
+    validate_output,
+)
+
+total_energy = Symbol("total_energy", units.energy)
+"""
+The total energy of the planet.
+
+Symbol:
+    :code:`E`
+"""
+
+average_kinetic_energy = Symbol("average_kinetic_energy", units.energy)
+r"""
+The kinetic energy of the planet averaged over time.
+
+Symbol:
+    :code:`<K>`
+
+Latex:
+    :math:`\langle K \rangle`
+"""
+
+law = Eq(total_energy, -1 * average_kinetic_energy)
+r"""
+:code:`E = -1 * <K>`
+
+Latex:
+    .. math::
+        E = - \langle K \rangle
+"""
+
+
+@validate_input(average_kinetic_energy_=average_kinetic_energy)
+@validate_output(total_energy)
+def calculate_total_energy(average_kinetic_energy_: Quantity) -> Quantity:
+    result = law.rhs.subs(average_kinetic_energy, average_kinetic_energy_)
+    return Quantity(result)

test/gravity/radial_motion/total_energy_is_negative_average_kinetic_energy_test.py

@@ -0,0 +1,30 @@
+from collections import namedtuple
+from pytest import fixture, raises
+from symplyphysics import (
+    assert_equal,
+    errors,
+    units,
+    Quantity,
+)
+from symplyphysics.laws.gravity.radial_motion import total_energy_is_negative_average_kinetic_energy as law
+
+Args = namedtuple("Args", "k")
+
+
+@fixture(name="test_args")
+def test_args_fixture() -> Args:
+    k = Quantity(3e8 * units.joule)
+    return Args(k=k)
+
+
+def test_law(test_args: Args) -> None:
+    result = law.calculate_total_energy(test_args.k)
+    assert_equal(result, -3e8 * units.joule)
+
+
+def test_bad_energy() -> None:
+    kb = Quantity(units.coulomb)
+    with raises(errors.UnitsError):
+        law.calculate_total_energy(kb)
+    with raises(TypeError):
+        law.calculate_total_energy(100)