From 719c112501f7384899a8d48f7ffd0d91f00c2ee1 Mon Sep 17 00:00:00 2001 From: ViniciusCMB Date: Tue, 16 Jun 2026 22:48:26 -0300 Subject: [PATCH 1/2] DOC: add aerodynamic surfaces user guide Add surfaces.rst documentation covering nose cones, fins, tails, and generic surfaces. This document explains the geometric parameters, available kinds, and how to add aerodynamic surfaces to a rocket. Fixes: None (new documentation) --- docs/user/aerodynamics/surfaces.rst | 350 ++++++++++++++++++++++++++++ docs/user/index.rst | 2 +- 2 files changed, 351 insertions(+), 1 deletion(-) create mode 100644 docs/user/aerodynamics/surfaces.rst diff --git a/docs/user/aerodynamics/surfaces.rst b/docs/user/aerodynamics/surfaces.rst new file mode 100644 index 000000000..38f266dca --- /dev/null +++ b/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 `. + + For the elliptical fin equations, see + :doc:`Elliptical Fins Equations `. + + For roll dynamics and cant angle conventions, see + :doc:`Roll Equations `. + + For the coordinate systems used by the Rocket class, see + :doc:`Rocket Class Axes Definitions ` and + :doc:`Positions and Coordinate Systems `. + +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 ` 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 `. + +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 ` 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 `. + +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 `_. + +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 `. + +.. 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 `: + Full derivation of the Barrowman method for individual fins, including + moment coefficients. +- :doc:`Elliptical Fins Equations `: + Geometric parameters and center of pressure for elliptical fins. +- :doc:`Roll Equations `: + Roll moment and damping equations for high-powered rockets. + +For coordinate system conventions: + +- :doc:`Rocket Class Axes Definitions ` +- :doc:`Positions and Coordinate Systems ` diff --git a/docs/user/index.rst b/docs/user/index.rst index 5afaee3a6..9d2b4835d 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -46,4 +46,4 @@ RocketPy's User Guide :caption: Further Analysis Function - Utilities \ No newline at end of file + Utilities Aerodynamic Surfaces From 9020311346e27e1cd0b1591307ccd366d4cdd417 Mon Sep 17 00:00:00 2001 From: ViniciusCMB Date: Wed, 1 Jul 2026 18:07:35 -0300 Subject: [PATCH 2/2] docs: add changelog entry for aerodynamic surfaces user guide [#1043] --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index df6a372b4..309a54eca 100644 --- a/CHANGELOG.md +++ b/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)