Patch documentation gravity

examples/gravity/satellite_velocity.py

@@ -17,14 +17,14 @@
 
 solution = Eq(centripetal_acceleration_law.law.rhs, free_fall_law.law.rhs)
 solution_applied = solution.subs(centripetal_acceleration_law.radius_of_curvature,
-    free_fall_law.planet_radius + free_fall_law.height_above_surface)
+    free_fall_law.planet_radius + free_fall_law.elevation)
 
 # first solution is negative and corresponds to the backwards direction of velocity - ignore it
 satellite_velocity = solve(solution_applied, centripetal_acceleration_law.speed,
     dict=True)[1][centripetal_acceleration_law.speed]
 
 print(
-    f"The formula for satellite linear velocity is: {print_expression(simplify(satellite_velocity))}"
+    f"The formula for satellite linear velocity is:\n{print_expression(simplify(satellite_velocity))}"
 )
 
 ## As a curve radius we are having radius of the planet plus desired height of the orbit. Let's take Earth as an example and 100km height.
@@ -35,7 +35,7 @@
 required_velocity_expression = satellite_velocity.subs({
     free_fall_law.planet_mass: planet_mass,
     free_fall_law.planet_radius: planet_radius_,
-    free_fall_law.height_above_surface: height_above_surface_
+    free_fall_law.elevation: height_above_surface_
 })
 
 result_velocity = Quantity(required_velocity_expression)

plots/gravity/free_fall_acceleration.py

@@ -1,7 +1,7 @@
 from sympy import solve, symbols
 from sympy.plotting import plot
 from sympy.plotting.plot import MatplotlibBackend
-from symplyphysics import (print_expression, units, convert_to, Quantity)
+from symplyphysics import (print_expression, units, convert_to, Quantity, quantities)
 from symplyphysics.laws.gravity import free_fall_acceleration_from_height as acceleration
 
 print(f"Formula is:\n{print_expression(acceleration.law)}")
@@ -17,8 +17,8 @@
 result_acceleration = solved.subs({
     acceleration.planet_mass: EARTH_MASS,
     acceleration.planet_radius: EARTH_RADIUS,
-    acceleration.height_above_surface: height_above_ground,
-    acceleration.units.gravitational_constant: gravity_constant_value
+    acceleration.elevation: height_above_ground,
+    quantities.gravitational_constant: gravity_constant_value
 })
 
 print(

symplyphysics/laws/gravity/area_rate_of_change_is_proportional_to_angular_momentum.py

@@ -1,41 +1,54 @@
+"""
+Area rate of change is proportional to angular momentum
+=======================================================
+
+The **law of areas**, also known as **Kepler's second law of planetary motion**,
+states that a line the connects a planet to the attracting body (the Sun) sweeps
+out equal areas in the plane of the planet's orbit in equal time intervals, and
+its rate of change is proportional to the planet's angular momentum. It is
+equivalent to saying that the planet's angular momentum is conserved.
+
+#. Sivukhin D.V. (1979), *Obshchiy kurs fiziki* [General course of Physics], vol. 1, pp. 312—314.
+"""
+
 from sympy import Eq, Derivative
 from symplyphysics import (
     units,
     Quantity,
-    Symbol,
-    Function,
-    print_expression,
     validate_input,
     validate_output,
     symbols,
+    clone_as_function,
 )
 
-# Description
-## The law of areas, also known as Kepler's second law of planetary motion, states that
-## a line the connects a planet to the attracting body (the Sun) sweeps out equal areas
-## in the plane of the planet's orbit in equal time intervals, and its rate of change
-## is proportional to the planets' angular momentum.
+time = symbols.time
+"""
+:symbols:`time`.
+"""
 
-# Note: this law is equivalent to saying that the planet's angular momentum is conserved.
+area_swept = clone_as_function(symbols.area, [time])
+"""
+:symbols:`area` swept by the planet.
+"""
 
-# Law: dA/dt = L/(2*m)
-## A - sweeping area
-## d/dt - derivative w.r.t. time
-## L - planet's angular momentum
-## m - planet's mass
+planet_angular_momentum = symbols.angular_momentum
+"""
+:symbols:`angular_momentum` of the planet.
+"""
 
-time = Symbol("time", units.time)
-area_swept = Function("area_swept", units.area)
-planet_angular_momentum = Symbol("planet_angular_momentum", units.length * units.momentum)
 planet_mass = symbols.mass
+"""
+:symbols:`mass` of the planet.
+"""
 
 law = Eq(Derivative(area_swept(time), time), planet_angular_momentum / (2 * planet_mass))
+"""
+:laws:symbol::
 
-# TODO: derive law from expression of area and definition of angular momentum
-
+:laws:latex::
+"""
 
-def print_law() -> str:
-    return print_expression(law)
+# TODO: derive law from expression of area and definition of angular momentum
 
 
 @validate_input(planet_angular_momentum_=planet_angular_momentum, planet_mass_=planet_mass)

symplyphysics/laws/gravity/corrected_planet_period_squared_is_proportional_to_cube_of_semimajor_axis.py

@@ -7,34 +7,34 @@
 the orbiting planet. If this assumption isn't made, the first and the second law stay the same, but
 the third law requires a revision. As a result, the period of the planet's rotation depends not only
 on the attracting mass, but also on the mass of the planet itself.
+
+**Notation:**
+
+#. :quantity_notation:`gravitational_constant`.
+
+**Links:**
+
+#. Sivukhin D.V. (1979), *Obshchiy kurs fiziki* [General course of Physics], vol. 1, p. 321, (59.3).
 """
 
 from sympy import Eq, pi, solve
-from sympy.physics.units import gravitational_constant
 from symplyphysics import (
-    units,
     Quantity,
-    Symbol,
     validate_input,
     validate_output,
     symbols,
     clone_as_symbol,
+    quantities,
 )
 
-rotation_period = Symbol("rotation_period", units.time)
+rotation_period = symbols.period
 """
-The planet's period of rotation.
-
-Symbol:
-    :code:`T`
+The planet's :symbols:`period` of rotation.
 """
 
-semimajor_axis = Symbol("semimajor_axis", units.length)
+semimajor_axis = symbols.semimajor_axis
 """
-The semi-major axis of the planet's orbit.
-
-Symbol:
-    :code:`a`
+The :symbols:`semimajor_axis` of the planet's orbit.
 """
 
 attracting_mass = clone_as_symbol(symbols.mass, display_symbol="M", display_latex="M")
@@ -49,14 +49,12 @@
 
 law = Eq(
     rotation_period**2,
-    (4 * pi**2 * semimajor_axis**3) / (gravitational_constant * (attracting_mass + planetary_mass)),
+    (4 * pi**2 * semimajor_axis**3) / (quantities.gravitational_constant * (attracting_mass + planetary_mass)),
 )
-r"""
-:code:`T^2 = (4 * pi^2 * a^3) / (G * (M + m))`
+"""
+:laws:symbol::
 
-Latex:
-    .. math::
-        T^2 = \frac{4 \pi^2 a^3}{G \left( M + m \right)}
+:laws:latex::
 """
 
 

symplyphysics/laws/gravity/easterly_deviation_from_plumbline_of_falling_bodies.py

@@ -1,39 +1,69 @@
+"""
+Easterly deviation from plumbline of falling bodies
+===================================================
+
+Suppose a body is falling freely in Earth's gravity field with its initial velocity being zero.
+Then the effect of the Coriolis force on the falling body can be found in the fact that it deflects
+from plumbline in the easterly and southerly (equatorial) directions.
+
+**Conditions:**
+
+#. The vector of free fall acceleration is constant.
+
+**Links:**
+
+#. Sivukhin D.V. (1979), *Obshchiy kurs fiziki* [General course of Physics], vol. 1, p. 355, (67.10).
+"""
+
 from sympy import Eq, cos, pi
 from symplyphysics import (
-    units,
-    angle_type,
     Quantity,
-    Symbol,
     validate_input,
     validate_output,
+    symbols,
+    clone_as_symbol,
 )
 from symplyphysics.core.symbols.quantities import scale_factor
 
-# Description
-## Suppose a body is falling freely in Earth's gravity field with its initial velocity being zero.
-## Then the effect of the Coriolis force on the falling body can be found in the fact that it deflects
-## from plumbline in the easterly and southerly (equatorial) directions.
+easterly_deviation_from_plumbline = clone_as_symbol(
+    symbols.euclidean_distance,
+    display_symbol="s_east",
+    display_latex="s_\\text{east}",
+)
+"""
+Easterly deviation of falling body from plumbline due to Earth's rotation.
+See :symbols:`euclidean_distance`
+"""
+
+fall_time = symbols.time
+"""
+:symbols:`time` of the body's fall.
+"""
 
-# Conditions
-## - The vector of free fall acceleration `g` is considered constant.
+rotation_period = symbols.period
+"""
+:symbols:`period` of the Earth's rotation.
+"""
 
-# Law: s_east = (4 * pi / 3) * (t / T) * h * cos(theta)
-## s_east - easterly deviation of falling body from plumbline due to Earth's rotation
-## t - time of the body's fall
-## T - period of Earth's rotation
-## h - initial elevation of the body from Earth's surface
-## theta - latitude of the place the body is located in
+initial_elevation = symbols.height
+"""
+Initial elevation (:symbols:`height`) of the body from the Earth's surface.
+"""
 
-easterly_deviation_from_plumbline = Symbol("easterly_deviation_from_plumbline", units.length)
-fall_time = Symbol("fall_time", units.time)
-rotation_period = Symbol("rotation_period", units.time)
-initial_elevation = Symbol("initial_elevation", units.length)
-latitude = Symbol("latitude", angle_type)
+latitude = symbols.latitude
+"""
+:symbols:`latitude` of the location of the body.
+"""
 
 law = Eq(
     easterly_deviation_from_plumbline,
     (4 * pi / 3) * (fall_time / rotation_period) * initial_elevation * cos(latitude),
 )
+"""
+:laws:symbol::
+
+:laws:latex::
+"""
 
 # TODO: derive from the solution of the relative motion equation in Earth's gravitational field.