DOC: add aerodynamic surfaces user guide

CHANGELOG.md

@@ -41,6 +41,7 @@ Attention: The newest changes should be on top -->
 - ENH: Monte Carlo Formatting Options [#947](https://github.com/RocketPy-Team/RocketPy/pull/947)
 - ENH: ENH: Auto-Detection of Pressure Conversion Factor [#966](https://github.com/RocketPy-Team/RocketPy/pull/966)
 - ENH: Auto-Detection of Pressure Conversion Factor [#966](https://github.com/RocketPy-Team/RocketPy/pull/966)
+- DOC: Add aerodynamic surfaces user guide [#1043](https://github.com/RocketPy-Team/RocketPy/pull/1043)
 - ENH: MNT: introduce pressure unit conversion when using forecast/reanalysis/ensemble data [#955](https://github.com/RocketPy-Team/RocketPy/pull/955)
 - ENH: Auto Populate Changelog [#919](https://github.com/RocketPy-Team/RocketPy/pull/919)
 - ENH: Adaptive Monte Carlo via Convergence Criteria [#922](https://github.com/RocketPy-Team/RocketPy/pull/922)

docs/user/aerodynamics/surfaces.rst

@@ -0,0 +1,350 @@
+.. _aerodynamic_surfaces:
+
+====================
+Aerodynamic Surfaces
+====================
+
+This page provides an overview of the aerodynamic surfaces available in
+RocketPy and explains how they connect to the rocket's simulation.
+
+RocketPy models the aerodynamic forces and moments generated by three types
+of surfaces: **nose cones**, **fins**, and **tails**. Each surface is
+defined by its geometric parameters and, optionally, by an airfoil profile.
+The aerodynamic coefficients are computed internally using the Barrowman
+method and are used during the flight simulation to evaluate the rocket's
+stability and control.
+
+.. seealso::
+
+   For the full mathematical derivations of the Barrowman method applied to
+   individual fins, see :doc:`Individual Fin Model </technical/aerodynamics/individual_fins>`.
+
+   For the elliptical fin equations, see
+   :doc:`Elliptical Fins Equations </technical/aerodynamics/elliptical_fins>`.
+
+   For roll dynamics and cant angle conventions, see
+   :doc:`Roll Equations </technical/aerodynamics/roll_equations>`.
+
+   For the coordinate systems used by the Rocket class, see
+   :doc:`Rocket Class Axes Definitions </user/rocket/rocket_axes>` and
+   :doc:`Positions and Coordinate Systems </user/positions>`.
+
+Nose Cones
+==========
+
+The nose cone is the forward-most aerodynamic surface of the rocket. It
+contributes to the normal force and the center of pressure position.
+
+Available Nose Cone Kinds
+-------------------------
+
+RocketPy supports the following nose cone shapes, specified via the ``kind``
+parameter:
+
+- ``"conical"``: A simple cone with a straight taper from base to tip.
+- ``"ogive"``: A tangent ogive shape, defined by the ratio of the tip
+  radius to the base radius (the ``bluffness`` parameter).
+- ``"elliptical"``: An elliptical cross-section nose cone.
+- ``"tangent"``: A tangent ogive with a rounded tip.
+- ``"von karman"``: A Von Karman ogive, a common choice for supersonic
+  rockets.
+- ``"parabolic"``: A parabolic nose cone shape.
+- ``"powerseries"``: A power series nose cone, controlled by the
+  ``power`` parameter (must be between 0 and 1). When this kind is used,
+  the ``bluffness`` parameter must be ``None`` or ``0``.
+- ``"lvhaack"``: A LV-Haack series nose cone.
+
+.. note::
+
+   The ``bluffness`` parameter controls the ratio between the radius of
+   the rounded tip and the radius of the base. It is only used for ogive
+   nose cones. For all other kinds, it should be ``None`` or ``0``.
+
+.. caution::
+
+   When ``kind="powerseries"``, the ``power`` parameter is required and
+   must satisfy ``0 < power <= 1``. A value of 1 produces a conical shape,
+   while lower values produce blunter shapes.
+
+Geometric Parameters
+--------------------
+
+All nose cones share the following parameters:
+
+- ``length``: The length of the nose cone along the rocket's centerline.
+- ``base_radius``: The radius of the nose cone at its base, which must
+  match the rocket's radius at the nose cone position.
+- ``position``: The position of the nose cone along the rocket's
+  centerline, relative to the coordinate system origin. See
+  :doc:`Positions and Coordinate Systems </user/positions>` for details.
+
+The center of pressure of the nose cone is computed internally and
+contributes to the overall aerodynamic model. The normal force coefficient
+derivative (CLalpha) depends on the nose cone kind and geometry.
+
+.. seealso::
+
+   For the class API, see :class:`rocketpy.NoseCone`.
+
+Fins
+====
+
+Fins are the primary stabilizing surfaces of a rocket. RocketPy supports
+three fin geometries and two ways to define them: as a **fin set** (the
+usual approach) or as an **individual fin**.
+
+Fin Sets vs. Individual Fins
+-----------------------------
+
+RocketPy distinguishes between two levels of fin definition:
+
+- **Fin set classes** (:class:`rocketpy.TrapezoidalFins`,
+  :class:`rocketpy.EllipticalFins`,
+  :class:`rocketpy.FreeFormFins`): These classes define a *set* of N
+  fins arranged symmetrically around the rocket. The aerodynamic
+  coefficients are computed using the Barrowman method, which accounts for
+  fin-body interference. This is the most common way to define fins.
+
+- **Individual fin classes** (:class:`rocketpy.TrapezoidalFin`,
+  :class:`rocketpy.EllipticalFin`,
+  :class:`rocketpy.FreeFormFin`): These classes define a *single* fin.
+  The moment coefficients are derived differently and are documented
+  separately. Individual fins are useful for canards, asymmetric
+  configurations, or when you need fine-grained control.
+
+.. seealso::
+
+   For the mathematical model of individual fins, including the moment
+   coefficient derivations, see
+   :doc:`Individual Fin Model </technical/aerodynamics/individual_fins>`.
+
+Fin Geometries
+--------------
+
+Trapezoidal Fins
+~~~~~~~~~~~~~~~~
+
+Trapezoidal fins are defined by a root chord, tip chord, span, and
+optionally a sweep length. They are the most common fin geometry in
+model rocketry.
+
+Parameters:
+
+- ``root_chord``: The chord length at the fin's root (where it meets the
+  rocket body).
+- ``tip_chord``: The chord length at the fin's tip. Setting this to 0
+  produces a triangular fin.
+- ``span``: The span of the fin, measured from the rocket body to the
+  fin tip.
+- ``sweep_length`` (optional): The distance from the root chord leading
+  edge to the tip chord leading edge, measured along the rocket's
+  centerline. If not provided, it is computed from the root chord, tip
+  chord, and span.
+- ``cant_angle`` (optional): The angle at which the fin is canted
+  relative to the rocket's centerline, in radians. A positive cant angle
+  produces a negative roll moment at zero angle of attack.
+
+.. caution::
+
+   The ``cant_angle`` convention is important for control surface design.
+   See :doc:`Roll Equations </technical/aerodynamics/roll_equations>` for
+   details on how cant angles affect roll, pitch, and yaw moments.
+
+Elliptical Fins
+~~~~~~~~~~~~~~~
+
+Elliptical fins are defined by a root chord and a span. The chord length
+varies elliptically from root to tip.
+
+Parameters:
+
+- ``root_chord``: The chord length at the fin's root.
+- ``span``: The span of the fin.
+
+.. seealso::
+
+   For the full mathematical derivation, see
+   :doc:`Elliptical Fins Equations </technical/aerodynamics/elliptical_fins>`.
+
+Free Form Fins
+~~~~~~~~~~~~~~
+
+Free form fins allow arbitrary fin shapes defined by a list of
+``(x, y)`` coordinates. This is useful for non-standard fin geometries
+that cannot be represented by trapezoidal or elliptical shapes.
+
+Parameters:
+
+- ``coordinates``: A list of ``(x, y)`` tuples defining the fin shape
+  in the fin coordinate frame.
+
+Common Fin Set Parameters
+-------------------------
+
+In addition to the geometry-specific parameters above, all fin sets
+share the following:
+
+- ``n``: The number of fins in the set (for fin set classes only).
+- ``position``: The position of the fin set along the rocket's
+  centerline, relative to the coordinate system origin.
+- ``angular_position`` (optional): The roll angle of the first fin in
+  the set, in degrees. Measured from the y-axis of the rocket's
+  coordinate system.
+- ``rocket_radius``: The radius of the rocket at the fin's position.
+  This is usually set automatically when adding fins to a rocket.
+- ``airfoil`` (optional): A tuple ``(path, units)`` specifying an
+  airfoil profile. See :ref:`airfoil_profiles` below.
+
+.. _airfoil_profiles:
+
+Airfoil Profiles
+----------------
+
+Fin aerodynamic coefficients can be enhanced by specifying an airfoil
+profile. Without an airfoil, fins are treated as flat plates.
+
+The ``airfoil`` parameter accepts a tuple of the form ``(path, units)``:
+
+- ``path``: Path to a CSV file containing the airfoil's lift coefficient
+  curve. The first column is the angle of attack, the second column is
+  the lift coefficient (CL).
+- ``units``: The unit of the angle of attack in the CSV file. Must be
+  either ``"radians"`` or ``"degrees"``.
+
+The CSV file should contain angle of attack points up to the stall point.
+The data is used to compute the fin's CLalpha (normal force coefficient
+derivative) during the simulation.
+
+.. note::
+
+   If ``airfoil`` is not provided or is ``None``, the fin is modeled as
+   a flat plate. This is a reasonable approximation for many model
+   rockets but may underestimate the normal force coefficient.
+
+.. seealso::
+
+   Airfoil data files can be obtained from
+   `Airfoil Tools <http://airfoiltools.com/>`_.
+
+Adding Fins to a Rocket
+-----------------------
+
+Fins can be added to a rocket using the ``Rocket`` class methods:
+
+.. code-block:: python
+
+   from rocketpy import Rocket, TrapezoidalFins
+
+   rocket = Rocket(
+       radius=0.0635,
+       mass=14.426,
+       inertia=(6.321, 6.321, 0.034),
+       power_off_drag="data/powerOffDragCurve.csv",
+       power_on_drag="data/powerOnDragCurve.csv",
+       center_of_mass_without_motor=0,
+       coordinate_system_orientation="tail_to_nose",
+   )
+
+   fin_set = rocket.add_trapezoidal_fins(
+       n=4,
+       root_chord=0.120,
+       tip_chord=0.060,
+       span=0.110,
+       position=-1.04956,
+       cant_angle=0.0,
+       airfoil=("data/airfoils/NACA0012-radians.txt", "radians"),
+   )
+
+.. seealso::
+
+   - :meth:`rocketpy.Rocket.add_trapezoidal_fins`
+   - :meth:`rocketpy.Rocket.add_elliptical_fins`
+   - :meth:`rocketpy.Rocket.add_free_form_fins`
+   - :meth:`rocketpy.Rocket.add_surfaces` (for individual fins)
+
+Tail
+====
+
+The tail is a transitional surface at the aft end of the rocket, typically
+used to reduce base drag. It is defined by a top radius, bottom radius,
+and length.
+
+Parameters:
+
+- ``top_radius``: The radius of the tail at its top (where it meets the
+  rocket body).
+- ``bottom_radius``: The radius of the tail at its bottom (aft end).
+- ``length``: The length of the tail along the rocket's centerline.
+- ``position``: The position of the tail along the rocket's centerline.
+
+The tail contributes to the normal force and center of pressure
+calculation. Its effect is generally smaller than that of the nose cone
+and fins.
+
+.. seealso::
+
+   For the class API, see :class:`rocketpy.Tail`.
+
+Generic Surfaces
+================
+
+For advanced use cases, RocketPy provides the
+:class:`rocketpy.GenericSurface` and
+:class:`rocketpy.LinearGenericSurface` classes. These allow you to
+specify aerodynamic force and moment coefficients directly, rather than
+relying on the built-in geometric models.
+
+This is useful when:
+
+- You have aerodynamic data from CFD simulations or wind tunnel tests.
+- You want to model aerodynamic surfaces that do not fit the built-in
+  geometries (e.g., canards with unusual shapes, air brakes).
+
+.. seealso::
+
+   For more information, see
+   :doc:`Generic Surfaces and Custom Aerodynamic Coefficients </user/rocket/generic_surface>`.
+
+.. note::
+
+   This section provides a brief overview of generic surfaces. A more
+   detailed treatment of coordinate frames and coefficient conventions
+   for generic surfaces is available in the referenced user guide page.
+
+Reference Area and Length
+=========================
+
+The aerodynamic forces and moments computed by each surface are scaled by
+a reference area and a reference length:
+
+- **Reference area**: The cross-sectional area of the rocket, computed
+  as :math:`\pi r^2` where :math:`r` is the rocket's radius.
+- **Reference length**: The diameter of the rocket (:math:`2r`).
+
+These values are used consistently across all aerodynamic surfaces and
+are set automatically from the rocket's radius.
+
+.. seealso::
+
+   For more details on how forces and moments are applied during the
+   simulation, see :class:`rocketpy.Rocket` and
+   :class:`rocketpy.Flight`.
+
+What's Next
+============
+
+This page covers the available surface types and their parameters. For
+deeper understanding of the underlying math:
+
+- :doc:`Individual Fin Model </technical/aerodynamics/individual_fins>`:
+  Full derivation of the Barrowman method for individual fins, including
+  moment coefficients.
+- :doc:`Elliptical Fins Equations </technical/aerodynamics/elliptical_fins>`:
+  Geometric parameters and center of pressure for elliptical fins.
+- :doc:`Roll Equations </technical/aerodynamics/roll_equations>`:
+  Roll moment and damping equations for high-powered rockets.
+
+For coordinate system conventions:
+
+- :doc:`Rocket Class Axes Definitions </user/rocket/rocket_axes>`
+- :doc:`Positions and Coordinate Systems </user/positions>`

docs/user/index.rst

@@ -47,4 +47,4 @@ RocketPy's User Guide
    :caption: Further Analysis
 
    Function <function.rst>
-   Utilities <analysis.rst>
+   Utilities <analysis.rst>  Aerodynamic Surfaces <aerodynamics/surfaces.rst>