:orphan:

.. ****************************************************************************
.. CUI
..
.. The Advanced Framework for Simulation, Integration, and Modeling (AFSIM)
..
.. The use, dissemination or disclosure of data in this file is subject to
.. limitation or restriction. See accompanying README and LICENSE for details.
.. ****************************************************************************

WsfNaturalMotionCircumnavigation
--------------------------------

.. class:: WsfNaturalMotionCircumnavigation inherits WsfOrbitalManeuver

**Input type:** :doc:`natural_motion_circumnavigation<../natural_motion_circumnavigation>`

:class:`WsfNaturalMotionCircumnavigation` is used to place the executing
platform, called the chaser, into a relative orbit around another platform,
called the target or chief. The chaser will first transfer to the
vicinity of the chief, and then insert into the natural motion circumnavigation.
See :doc:`Natural Motion Circumnavigation Details <../nmc_details>` for details.

Several conditions must be met for the transfer orbit to be successful:

.. _conditions:

* The :class:`target point<WsfTargetPoint>` must reference a valid :class:`WsfLocalTrack` with both valid location and velocity;
* The transfer orbit can only be hyperbolic if the mover executing the maneuver supports hyperbolic propagation;
* The transfer orbit must not intersect earth;
* When optimizing, a valid solution must exist for the provided optimization option;
* The expended energy for the transfer must be less than the available delta-v.

  .. note:: The targeting algorithm is direct (less than one orbit).  Phasing orbits are not considered.

Methods
*******

.. method:: static WsfNaturalMotionCircumnavigation Construct(WsfOrbitalEventCondition aCondition, WsfTargetPoint aTargetPoint, int aOptimizeOption, double aMaximumDeltaTime, double aMaximumDeltaV, double aOrbitSize)

   Create a :class:`WsfNaturalMotionCircumnavigation` with the intent of finding an optimal transfer solution in delta-V or time, using the following:

   * **aCondition**:  A specific :class:`WsfOrbitalEventCondition`.
   * **aTargetPoint**: A :class:`WsfTargetPoint` instance specifying the target of this maneuver. This target must be a track target, and should not specify any position or velocity offsets, offset time, or lag time.
   * **aOptimizeOption**: The return value from a :method:`WsfNaturalMotionCircumnavigation.EARLIEST_TIME` or :method:`WsfNaturalMotionCircumnavigation.LEAST_DELTA_V`.
   * **aMaximumDeltaTime**: The maximum time in seconds after the maneuver begins to consider in computing a solution.
   * **aMaximumDeltaV**: The maximum delta-V in meters per second to consider when computing a solution.
   * **aOrbitSize**: The size in meters of the semi-major-axis of the relative orbit of the chaser around the chief. The provided value must be greater than zero.

.. method:: static WsfNaturalMotionCircumnavigation Construct(WsfOrbitalEventCondition aCondition, WsfTargetPoint aTargetPoint, WsfOrbitalOptimizationCost aCost, double aMaximumDeltaTime, double aMaximumDeltaV, double aOrbitSize)

   Create a :class:`WsfNaturalMotionCircumnavigation` with the intent of finding an transfer solution minimizing the provided cost function, using the following:

   * **aCondition**:  A specific :class:`WsfOrbitalEventCondition`.
   * **aTargetPoint**: A :class:`WsfTargetPoint` instance specifying the target of this maneuver. This target must be a track target, and should not specify any position or velocity offsets, offset time, or lag time.
   * **aCost**: A :class:`WsfOrbitalOptimizationCost` instance specifying the cost function to minimize.
   * **aMaximumDeltaTime**: The maximum time in seconds after the maneuver begins to consider in computing a solution.
   * **aMaximumDeltaV**: The maximum delta-V in meters per second to consider when computing a solution.
   * **aOrbitSize**: The size in meters of the semi-major-axis of the relative orbit of the chaser around the chief. The provided value must be greater than zero.

.. method:: static WsfNaturalMotionCircumnavigation Construct(WsfOrbitalEventCondition aCondition, WsfTargetPoint aTargetPoint, double aDeltaTime, double aOrbitSize)

   Create a :class:`WsfNaturalMotionCircumnavigation` without optimizing the transfer. If all prerequisite conditions_ are met, the transfer will take the specified time to complete once the maneuver begins.

   * **aCondition**:  A specific :class:`WsfOrbitalEventCondition`
   * **aTargetPoint**: A :class:`WsfTargetPoint` instance specifying the target of this maneuver. This target must be a track target, and should not specify any position or velocity offsets, offset time, or lag time.
   * **aDeltaTime**: The time after the maneuver begins when the transfer is planned to complete.
   * **aOrbitSize**: The size in meters of the semi-major-axis of the relative orbit of the chaser around the chief. The provided value must be greater than zero.

.. method:: int EARLIEST_TIME()

   Attempt to optimize the maneuver such that it will execute at the earliest possible time, up to delta-t and delta-V constraints provided during construction.

.. method:: int LEAST_DELTA_V()

   Attempt to optimize the maneuver such that it will execute with the least possible delta-v, up to delta-t and delta-V constraints provided during construction.

.. method:: double OrbitSize()

   Return the relative semi-major-axis in meters of the resulting natural motion circumnavigation (see :doc:`Natural Motion Circumnavigation Details <../nmc_details>`).

.. method:: double OrbitPhase()

   Return the phase of the insertion point in degrees for the resulting natural motion circumnavigation (see :doc:`Natural Motion Circumnavigation Details <../nmc_details>`). Unless :method:`WsfNaturalMotionCircumnavigation.SetOrbitPhase` has been called on this object, this will return the default value of 0.

.. method:: double OutOfPlaneAmplitude()

   Return the out-of-plane amplitude in meters for the resulting natural motion circumnavigation (see :doc:`Natural Motion Circumnavigation Details <../nmc_details>`). Unless :method:`WsfNaturalMotionCircumnavigation.SetOutOfPlaneAmplitude` has been called on this object, this will return the default value of 0.

.. method:: double OutOfPlanePhase()

   Return the out-of-plane phase in degrees for the resulting natural motion circumnavigation (see :doc:`Natural Motion Circumnavigation Details <../nmc_details>`). Unless :method:`WsfNaturalMotionCircumnavigation.SetOutOfPlanePhase` has been called on this object, this will return the default value of 0.

.. method:: void SetOrbitSize(double aOrbitSize)

   Set the relative semi-major-axis in meters of the resulting natural motion circumnavigation (see :doc:`Natural Motion Circumnavigation Details <../nmc_details>`). The provided size must be greater than zero.

.. method:: void SetOrbitPhase(double aOrbitPhase)

   Set the phase of the insertion point in degrees for the resulting natural motion circumnavigation (see :doc:`Natural Motion Circumnavigation Details <../nmc_details>`).

.. method:: void SetOutOfPlaneAmplitude(double aOutOfPlaneAmplitude)

   Set the out-of-plane amplitude in meters for the resulting natural motion circumnavigation (see :doc:`Natural Motion Circumnavigation Details <../nmc_details>`). The provided value must be non-negative.

.. method:: void SetOutOfPlanePhase(double aOutOfPlanePhase)

   Set the out-of-plane phase in degrees for the resulting natural motion circumnavigation (see :doc:`Natural Motion Circumnavigation Details <../nmc_details>`).