Merge pull request #64 from JuliaSpaceMissionDesign/dev

Dev

docs/src/Examples/gen/e01_cr3bp.jl

@@ -0,0 +1,14 @@
+using FrameTransformations
+
+CR3BP = FrameSystem{2, Float64}()
+
+add_axes_root!(CR3BP, :InertialAx, 1)
+add_point_root!(CR3BP, :EMBc, 1, 1)
+
+using ReferenceFrameRotations
+
+f(t) = angle_to_dcm(t, :Z)
+
+add_axes_rotating!(CR3BP, :SynodicAx, 2, 1, f)
+
+# This file was generated using Literate.jl, https://github.com/fredrikekre/Literate.jl

docs/src/Examples/gen/e01_cr3bp.md

@@ -0,0 +1,58 @@
+```@meta
+EditURL = "../e01_cr3bp.jl"
+```
+
+# [Use Case: CR3BP](@id example_01_cr3bp)
+_This example was generated on 2024-05-31T10:00:28.409._
+
+The power of the [`FrameSystem`](@ref) is its capability to handle axes
+transformations and point translations of both high-accuracy and simplified
+models. The use-case here presented includes the case of the Circular-Restricted
+Three-Body Problem (CR3BP) rotating frame transformation handling.
+
+In particular, when dealing with the [CR3BP](https://orbital-mechanics.space/the-n-body-problem/circular-restricted-three-body-problem.html),
+mission analysis are used to exploit non-dimensional, rotating coordinates
+to express the equations of motion and perform the computations.
+
+In this tutorial, we create a [`FrameSystem`](@ref) to handle transformations
+within the Earth-Moon CR3BP, which is characterized by a mass ratio of
+approximately `μ = 0.012`. We start off by creating a frame system without any
+ephemeris provider, since we are using a simplified model.
+
+````@example e01_cr3bp
+using FrameTransformations
+
+CR3BP = FrameSystem{2, Float64}()
+````
+
+As always, the first step requires the definition of the root axes and points.
+In this case, we use the a generic set of _inertial axes_ and the Earth-Moon
+Barycenter (EMB).
+
+````@example e01_cr3bp
+add_axes_root!(CR3BP, :InertialAx, 1)
+add_point_root!(CR3BP, :EMBc, 1, 1)
+````
+
+We now proceed to add our synodic axes: in the CR3BP these are uniformly
+rotating with respect to the `InertialAx` about the Z-axis. Therefore, we
+leverage rotating axes.
+
+````@example e01_cr3bp
+using ReferenceFrameRotations
+
+f(t) = angle_to_dcm(t, :Z)
+
+add_axes_rotating!(CR3BP, :SynodicAx, 2, 1, f)
+````
+
+Note that there is no need to specify the rotation derivatives, as they'll
+be computed by  automatic differentiation via the
+[ForwardDiff](https://github.com/JuliaSpaceMissionDesign/Ephemerides.jl) package.
+For performace-critical transformations, however, it is reccomended to manually
+define these derivatives.
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+

docs/src/Examples/gen/e02_hifi.jl

@@ -0,0 +1,21 @@
+using FrameTransformations
+using Ephemerides
+using LinearAlgebra
+using ReferenceFrameRotations
+
+url_pck = "https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/moon_pa_de421_1900-2050.bpc";
+url_spk = "https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de432s.bsp";
+
+EPH = EphemerisProvider([download(url_spk), download(url_pck)])
+
+FRAMES = FrameSystem{3, Float64}()
+
+add_axes_icrf!(FRAMES)
+
+add_point_root!(FRAMES, :SSB, 0, 1)
+add_point_ephemeris!(FRAMES, EPH, :EMB, 3)
+add_point_ephemeris!(FRAMES, EPH, :Sun, 10)
+add_point_ephemeris!(FRAMES, EPH, :Earth, 399)
+add_point_ephemeris!(FRAMES, EPH, :Moon, 301)
+
+# This file was generated using Literate.jl, https://github.com/fredrikekre/Literate.jl

docs/src/Examples/gen/e02_hifi.md

@@ -0,0 +1,62 @@
+```@meta
+EditURL = "../e02_hifi.jl"
+```
+
+# [Use Case: High Fidelity](@id example_02_hifi)
+_This example was generated on 2024-05-31T10:00:28.413._
+
+Once the general structure of the [`FrameSystem`](@ref) is understood, we can pass to
+a use case in which we want to build and exploit our frame system to perform computations
+in a high-fidelity environment.
+
+### Frame system setup
+
+In this example, we plan on using ephemeris data to retrieve accurate positions
+of the planets and the orientation of certain reference frames. Therefore, we
+create an ephemeris provider object leveraging our own
+[`Ephemerides.jl`](https://github.com/JuliaSpaceMissionDesign/Ephemerides.jl) package
+and use it to generate a frame system instance:
+
+````@example e02_hifi
+using FrameTransformations
+using Ephemerides
+using LinearAlgebra
+using ReferenceFrameRotations
+
+url_pck = "https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/moon_pa_de421_1900-2050.bpc";
+url_spk = "https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de432s.bsp";
+
+EPH = EphemerisProvider([download(url_spk), download(url_pck)])
+
+FRAMES = FrameSystem{3, Float64}()
+````
+
+Once the graph is created, we assign the `ICRF` (International Celestial Reference
+Frame) as our set of inertial root-axes:
+
+````@example e02_hifi
+add_axes_icrf!(FRAMES)
+````
+
+These axes are practically coincident with the `GCRF`.
+
+In this scenario, we will be working within the Cislunar environment, therefore
+we will need the major bodies that influence this dynamic regime, i..e, the Earth,
+the Moon and the Sun. To do so, we also define the Solar System Barycenter (SSB) and
+the Earth-Moon Barycenter (EMB) as the ephemeris data of the remaining bodies is
+expressed with respect to those.
+
+For this example, we will assume the SSB is our root point:
+
+````@example e02_hifi
+add_point_root!(FRAMES, :SSB, 0, 1)
+add_point_ephemeris!(FRAMES, EPH, :EMB, 3)
+add_point_ephemeris!(FRAMES, EPH, :Sun, 10)
+add_point_ephemeris!(FRAMES, EPH, :Earth, 399)
+add_point_ephemeris!(FRAMES, EPH, :Moon, 301)
+````
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+

docs/src/Examples/gen/e03_customorb.jl

@@ -0,0 +1,25 @@
+using FrameTransformations
+
+G = FrameSystem{4, Float64}()
+
+add_axes_icrf!(G)
+add_point_root!(G, :Earth, 399, 1)
+
+using JSMDInterfaces.Math: interpolate
+using JSMDUtils.Math: InterpCubicSplines
+
+c = 2π/86400
+de = 0:3600:2*86400;
+fv(t) = [cos(c*t), sin(c*t), 0, -c*sin(c*t), c*cos(c*t), 0];
+fv2(t) = [sin(c*t), cos(c*t), 0];
+const ORB1 = InterpCubicSplines(de, hcat([fv(e) for e in de]...));
+const ORB2 = InterpCubicSplines(de, hcat([fv2(e) for e in de]...));
+
+add_point_dynamical!(G, :SC1, -1, 399, 1, t->interpolate(ORB1, t)[1:3], t->interpolate(ORB1, t))
+add_point_dynamical!(G, :SC2, -2, 399, 1, t->interpolate(ORB2, t))
+
+vector12(G, 399, -1, 1, 12345.0)
+
+vector12(G, -1, -2, 1, 12345.0)
+
+# This file was generated using Literate.jl, https://github.com/fredrikekre/Literate.jl

docs/src/Examples/gen/e03_customorb.md

@@ -0,0 +1,90 @@
+```@meta
+EditURL = "../e03_customorb.jl"
+```
+
+# [Use Case: Custom spacecraft orbit](@id example_03_orb)
+_This example was generated on 2024-05-31T10:00:28.419._
+
+Once the general structure of the [`FrameSystem`](@ref) is understood, we can pass to
+a use case in which we want to build and exploit our frame system to perform computations
+inserting a custom orbit. This becomes especially crucial in complex cases like Trajectory
+Optimization and Navigation Analysis.
+
+In such scenarios, the trajectory is under design, and the trajectory information might
+not be completely available. Moreover, in these cases derivatives could be required for
+various quantities such as time, states, and parameters.
+
+In this context, we shall remember that `FrameTransformations` is able to perform operations,
+including AD, on the frames **independent variable**, e.g. only time.
+
+A proper orbit representation is essential to avoid perturbation confusion and ensure
+proper custom orbit handling. For this purpose, two point types can seems suitable:
+`updatable` and `dynamical` points.
+In this case, however, `updatable` points are not well-suited as they are essentially
+constants for the AD system. Then, `dynamical` points can effectively handle this scenario.
+
+### Frame system setup
+
+First of all, a new [`FrameSystem`](@ref) shall be created.
+
+````@example e03_customorb
+using FrameTransformations
+
+G = FrameSystem{4, Float64}()
+
+add_axes_icrf!(G)
+add_point_root!(G, :Earth, 399, 1)
+````
+
+!!! note
+    As the orbit considered in this example is custom, there is no requirement
+    to load ephemeris.
+
+### Custom orbit model
+
+A custom orbit model is then required. In this case two dummy orbits are
+created and stored in a `CubicSpline` object.
+
+````@example e03_customorb
+using JSMDInterfaces.Math: interpolate
+using JSMDUtils.Math: InterpCubicSplines
+
+c = 2π/86400
+de = 0:3600:2*86400;
+fv(t) = [cos(c*t), sin(c*t), 0, -c*sin(c*t), c*cos(c*t), 0];
+fv2(t) = [sin(c*t), cos(c*t), 0];
+const ORB1 = InterpCubicSplines(de, hcat([fv(e) for e in de]...));
+const ORB2 = InterpCubicSplines(de, hcat([fv2(e) for e in de]...));
+nothing #hide
+````
+
+### Custom orbit handling
+
+Given the custom orbit model, [`add_point_dynamical!`](@ref) could be used
+to link it to the frame system.
+
+Insert dynamical points
+
+````@example e03_customorb
+add_point_dynamical!(G, :SC1, -1, 399, 1, t->interpolate(ORB1, t)[1:3], t->interpolate(ORB1, t))
+add_point_dynamical!(G, :SC2, -2, 399, 1, t->interpolate(ORB2, t))
+````
+
+Once in the frame system, AD could be exploited to retrieve states+gradients w.r.t.
+time in any registered frame:
+
+````@example e03_customorb
+vector12(G, 399, -1, 1, 12345.0)
+````
+
+It is also possible to use the computational graph to compute quantities between
+completely custom states representations:
+
+````@example e03_customorb
+vector12(G, -1, -2, 1, 12345.0)
+````
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+

docs/src/Tutorials/gen/t00_frames.jl

@@ -0,0 +1,35 @@
+using FrameTransformations
+using Tempo
+
+F = FrameSystem{2, Float64}()
+
+F = FrameSystem{2, Float64, InternationalAtomicTime}()
+
+has_point(F, 1)
+
+has_axes(F, 1)
+
+has_direction(F, :Root)
+
+axes(F)
+
+points(F)
+
+order(F)
+
+FrameTransformations.timescale(F)
+
+using Ephemerides, Downloads
+
+url = "https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/a_old_versions/de421.bsp";
+eph = EphemerisProvider(Downloads.download(url));
+
+F = FrameSystem{2, Float64}()
+
+add_axes_icrf!(F)
+add_point_root!(F, :SSB, 0, 1)
+
+add_point_ephemeris!(F, eph, :Sun, 10)
+add_point_ephemeris!(F, eph, :EMB, 3)
+
+# This file was generated using Literate.jl, https://github.com/fredrikekre/Literate.jl