Law: Kepler's constant (#857)

* Create law and test

* Fix documentation

symplyphysics/laws/gravity/__init__.py

@@ -0,0 +1,7 @@
+"""
+Gravity
+=======
+
+*Gravity* is a fundamental interaction which causes mutual attraction between all things that
+have mass.
+"""

symplyphysics/laws/gravity/keplers_constant_via_attracting_body_mass.py

@@ -0,0 +1,54 @@
+"""
+Kepler's constant via attracting body mass
+==========================================
+
+Kepler's constant is a physical quantity that only depends on the gravitational constant and the mass of
+the orbited body, such as the Sun. It is constant in the sense that all planets that orbit the same body
+approximately have the same value of the Kepler's constant.
+"""
+
+from sympy import Eq, pi
+from sympy.physics.units import gravitational_constant
+from symplyphysics import (
+    units,
+    Quantity,
+    Symbol,
+    validate_input,
+    validate_output,
+    symbols,
+    clone_symbol,
+)
+
+keplers_constant = Symbol("keplers_constant", units.length**3 / units.time**2)
+r"""
+Symbol:
+    K
+
+Latex:
+    :math:`\mathfrak{K}`
+"""
+
+attracting_body_mass = clone_symbol(symbols.basic.mass, "attracting_body_mass")
+"""
+The :attr:`~symplyphysics.symbols.basic.mass` of the attracting body.
+
+Symbol:
+    M
+"""
+
+law = Eq(keplers_constant, gravitational_constant * attracting_body_mass / (4 * pi**2))
+r"""
+K = G * M / (4 * pi^2)
+
+Latex:
+    :math:`\mathfrak{K} = \frac{G M}{4 \pi^2}`
+"""
+
+
+@validate_input(attracting_body_mass_=attracting_body_mass)
+@validate_output(keplers_constant)
+def calculate_keplers_constant(attracting_body_mass_: Quantity) -> Quantity:
+    result = law.rhs.subs({
+        attracting_body_mass: attracting_body_mass_,
+    })
+    return Quantity(result)

symplyphysics/quantities/__init__.py

@@ -1,5 +1,5 @@
 """
-Physics constants
+Physical constants
 ==================
 
 Contains useful physical constants. Fundamental constants can be also found in `sympy.physics.units`_ module.
@@ -11,41 +11,41 @@
 from ..core.symbols.quantities import Quantity
 
 standard_conditions_temperature = Quantity(273.15 * units.kelvin)
-"""
+r"""
 Zero Celsius degrees. The temperature at which water freezes.
 It is also temperature for Standard Temperature and Pressure (STP)
 
 Symbol:
     t0
 
 Latex:
-    :math:`t_0`
+    :math:`t_\text{std}`
 """
 
 standard_laboratory_temperature = Quantity(298 * units.kelvin)
-"""
+r"""
 Approximately 25 Celsius degrees. Commonly used temperature for tabulation purposes.
 
 Symbol:
     t_std
 
 Latex:
-    :math:`t_{std}`
+    :math:`t_\text{lab}`
 """
 
 electron_rest_mass = Quantity(9.1093837015e-31 * units.kilogram)
-"""
+r"""
 Mass of stationary electron
 
 Symbol:
     m_e
 
 Latex:
-    :math:`m_e`
+    :math:`m_\text{e}`
 """
 
 bohr_radius = Quantity(0.529e-10 * units.meter)
-"""
+r"""
 The Bohr radius is the radius of the electron orbit of the hydrogen atom closest
 to the nucleus in the atomic model proposed by Niels Bohr.
 
@@ -57,15 +57,27 @@
 """
 
 hydrogen_ionization_energy = Quantity(13.6 * units.electronvolt)
-"""
+r"""
 The ionization energy is the smallest energy required to remove an electron from
 a free atom in its basic energy state to infinity.
 
 Symbol:
     IE_h
 
 Latex:
-    :math:`{IE}_h`
+    :math:`\mathrm{IE}_\text{H}`
+"""
+
+solar_mass = Quantity(1.9884e30 * units.kilogram)
+r"""
+The solar mass is a standard unit of mass in astronomy approximately equal to the mass
+of the Sun.
+
+Symbol:
+    M_Sun
+
+Latex:
+    :math:`\mathrm{M}_\odot`
 """
 
 __all__ = [
@@ -74,4 +86,5 @@
     "electron_rest_mass",
     "bohr_radius",
     "hydrogen_ionization_energy",
+    "solar_mass",
 ]

test/gravity/keplers_constant_via_attracting_body_mass_test.py

@@ -0,0 +1,30 @@
+from collections import namedtuple
+from pytest import fixture, raises
+from symplyphysics import (
+    assert_equal,
+    Quantity,
+    errors,
+    units,
+)
+from symplyphysics.laws.gravity import keplers_constant_via_attracting_body_mass as law
+from symplyphysics.quantities import solar_mass
+
+Args = namedtuple("Args", "m")
+
+
+@fixture(name="test_args")
+def test_args_fixture() -> Args:
+    return Args(m=solar_mass)
+
+
+def test_law(test_args: Args) -> None:
+    result = law.calculate_keplers_constant(test_args.m)
+    assert_equal(result, 7.5e-6 * units.astronomical_unit**3 / units.day**2)
+
+
+def test_bad_mass() -> None:
+    mb = Quantity(units.coulomb)
+    with raises(errors.UnitsError):
+        law.calculate_keplers_constant(mb)
+    with raises(TypeError):
+        law.calculate_keplers_constant(100)