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) 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 580b9c612..2a28fa23d 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -47,4 +47,4 @@ RocketPy's User Guide :caption: Further Analysis Function - Utilities \ No newline at end of file + Utilities Aerodynamic Surfaces