eop loading tutorials

JuliaSpaceMissionDesign · Oct 5, 2024 · 2f61538 · 2f61538
1 parent 6818d4a
commit 2f61538
Show file tree

Hide file tree

Showing 11 changed files with 199 additions and 122 deletions.
diff --git a/docs/generate.jl b/docs/generate.jl
@@ -0,0 +1,33 @@
+using Literate
+using Dates
+
+# TODO: Remove items from `SKIPFILE` as soon as they run on the latest stable 
+ONLYSTATIC = []
+EXAMPLE_DIRS = ["Tutorials",]
+SKIPFILE = []
+
+function update_date(content)
+    content = replace(content, "DATEOFTODAY" => Dates.DateTime(now()))
+    return content
+end
+
+for edir in EXAMPLE_DIRS
+    gen_dir = joinpath(@__DIR__, "src", edir, "gen")
+    example_dir = joinpath(@__DIR__, "src", edir)
+    for example in filter!(x -> endswith(x, ".jl"), readdir(example_dir))
+        if example in SKIPFILE
+            continue
+        end
+        input = abspath(joinpath(example_dir, example))
+        script = Literate.script(input, gen_dir)
+        code = strip(read(script, String))
+        mdpost(str) = replace(str, "@__CODE__" => code)
+        Literate.markdown(
+            input, gen_dir,
+            preprocess=update_date,
+            postprocess=mdpost,
+            documenter=!(example in ONLYSTATIC)
+        )
+    end
+end
+
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,8 +1,13 @@
 using Documenter, IERSConventions
-using Pkg 
+using Pkg
 
 const CI = get(ENV, "CI", "false") == "true"
 
+if CI
+    Pkg.add("Literate")
+end
+
+include("generate.jl")
 
 makedocs(;
     authors="Julia Space Mission Design Development Team",
@@ -12,14 +17,11 @@ makedocs(;
     pages=[
         "Home" => "index.md",
         "Tutorials" => [
-            "01 - Introduction" => "tutorials/t01_intro.md"
-        ], 
-
-        "Benchmarks" => "benchmarks.md",
-
+            "01 - Loading EOPs" => "Tutorials/gen/t01_load.md"
+        ],
         "API" => [
-            "Public API" => "api/api.md",
-            "Low-level API" => "api/lapi.md"
+            "Public API" => "API/api.md",
+            "Low-level API" => "API/lapi.md"
         ]
     ],
     clean=true,

diff --git a/docs/src/api/api.md → docs/src/API/api.md b/docs/src/api/api.md → docs/src/API/api.md
diff --git a/docs/src/api/lapi.md → docs/src/API/lapi.md b/docs/src/api/lapi.md → docs/src/API/lapi.md
diff --git a/docs/src/Tutorials/gen/.gitignore b/docs/src/Tutorials/gen/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/docs/src/Tutorials/t01_load.jl b/docs/src/Tutorials/t01_load.jl
@@ -0,0 +1,38 @@
+# # [Loading IERS EOP data](@id tutorial_01_load)
+# _This example was generated on DATEOFTODAY._
+
+# When working with frames associated with the Earth, it is imperative to incorporate 
+# Earth Orientation Parameters (EOP) data. The EOP data are required for the accurate 
+# construction of  various Earth associated frames.
+
+# ### Creating compatible EOP file
+
+# To minimize dependencies on external sources, `IERSConventions` defines a 
+# standardized format for EOP data. The expected format consists of a file with 
+# the '.eop.dat' extension. This file should contain columns representing different 
+# Earth orientation parameters. 
+
+# In order to ensure that the provided EOP file adheres to this format, USNO standard files can 
+# be processed using [`eop_generate_from_txt`](@ref) or [`eop_generate_from_csv`](@ref) 
+# functions:
+
+using IERSConventions
+
+finals = download(
+    "https://datacenter.iers.org/data/latestVersion/finals.all.iau2000.txt",
+    "/tmp/finals2000A.txt"
+)
+filename = "/tmp/iau2000a"
+eop_generate_from_txt(iers2010a, finals, filename)
+
+# This will create a `iau2000a.eop.dat` file to be used later.
+
+# ### Loading EOP data 
+
+# Once a EOP file compatible with the reader is avaliable, the data could be 
+# loaded in the environment for usage of all the methods within `IERSConventions` using 
+# the [`eop_load_data!`](@ref) method, as follows:
+
+eop_load_data!(iers2010a, filename * ".eop.dat")
+
+# It is possible to override the data, e.g. re-use this functions as many times as needed.
diff --git a/docs/src/benchmarks.md b/docs/src/benchmarks.md
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -2,7 +2,9 @@
 
 _IERS Conventions made easy._
 
-The aim of this package is to provide a set of standardised functions that allow the user to easily handle all the computations related to the IERS, from the earlier 1996 up to the latest 2010 conventions.
+The aim of this package is to provide a set of standardised functions that allow the user to 
+easily handle all the computations related to the IERS, from the earlier 1996 up to the 
+latest 2010 conventions.
 
 ## Installation 
 

diff --git a/docs/src/tutorials/t01_intro.md b/docs/src/tutorials/t01_intro.md
diff --git a/src/eop/loaders.jl b/src/eop/loaders.jl
@@ -12,22 +12,22 @@ function eop_load_data!(m::IERSModel, filename)
     eop_set_data!(m, filename)
 
     # Initialise the interpolators 
-    IERS_EOP.init = true 
+    IERS_EOP.init = true
 
     # Set polar motion
     IERS_EOP.xp = InterpAkima(IERS_EOP_DATA.cent_TT, IERS_EOP_DATA.xp)
     IERS_EOP.yp = InterpAkima(IERS_EOP_DATA.cent_TT, IERS_EOP_DATA.yp)
 
     IERS_EOP.lod = InterpAkima(IERS_EOP_DATA.cent_TT, IERS_EOP_DATA.LOD)
     IERS_EOP.ut1_tt = InterpAkima(IERS_EOP_DATA.cent_TT, IERS_EOP_DATA.UT1_TT)
-    
+
     # Set nutation correction interpolators
     IERS_EOP.nut1996 = NutCorrectionsInterpolator(IERS_EOP_DATA.cent_TT, IERS_EOP_DATA.nut1996)
     IERS_EOP.nut2003 = NutCorrectionsInterpolator(IERS_EOP_DATA.cent_TT, IERS_EOP_DATA.nut2003)
     IERS_EOP.nut2010 = NutCorrectionsInterpolator(IERS_EOP_DATA.cent_TT, IERS_EOP_DATA.nut2010)
 
     @info "EOP initialised from file `$(filename)`."
-    nothing 
+    nothing
 
 end
 
@@ -37,7 +37,7 @@ end
 Unload all the EOP data that has been loaded during the session. 
 """
 function eop_unload_data!()
-    
+
     # Here we are not actually removing the data from the EOP data structures, 
     # but we still make sure that the parameters that are used to verify whether 
     # there is available EOP data are set to false. 
@@ -46,7 +46,7 @@ function eop_unload_data!()
     IERS_EOP.init = false
 
     @info "EOP data successfully unloaded."
-    nothing 
+    nothing
 
 end
 
@@ -67,19 +67,19 @@ function eop_set_data!(m::IERSModel, filename)
     end
 
     # Compute TT centuries
-    tt_c = days_tt/Tempo.CENTURY2DAY
+    tt_c = days_tt / Tempo.CENTURY2DAY
 
     # Set data time stamps
     IERS_EOP_DATA.filename = filename
     IERS_EOP_DATA.days_UTC = days_utc
-    IERS_EOP_DATA.cent_TT  = tt_c
+    IERS_EOP_DATA.cent_TT = tt_c
 
     # Set TT-to-UT1 offset and LOD
-    IERS_EOP_DATA.UT1_TT = ut1_tt 
-    IERS_EOP_DATA.LOD    = lod
+    IERS_EOP_DATA.UT1_TT = ut1_tt
+    IERS_EOP_DATA.LOD = lod
 
     # Set polar motion coordinates 
-    IERS_EOP_DATA.xp = xp 
+    IERS_EOP_DATA.xp = xp
     IERS_EOP_DATA.yp = yp
 
     # Transforma the CIP/nutation corrections from model `m` to the remaining ones.
@@ -96,42 +96,42 @@ function set_cip_nutation_corr!(m::IERSModel, tt_c, δX, δY, δΔψ, δΔϵ)
     δX_96, δY_96 = zeros(n), zeros(n)
     δX_03, δY_03 = zeros(n), zeros(n)
     δX_10, δY_10 = zeros(n), zeros(n)
-    
+
     δΔψ_96, δΔϵ_96 = zeros(n), zeros(n)
     δΔψ_03, δΔϵ_03 = zeros(n), zeros(n)
     δΔψ_10, δΔϵ_10 = zeros(n), zeros(n)
 
     # radians to arcseconds factor
-    k = 648000/π
+    k = 648000 / π
 
     @inbounds for j in eachindex(tt_c)
 
         # Compute CIP coordinates with the input model
         xin, yin = cip_xy(m, tt_c[j])
-        
+
         # Retrieve corrections in radians
-        δXj = δX[j]/k
-        δYj = δY[j]/k
+        δXj = δX[j] / k
+        δYj = δY[j] / k
 
-        δΔψj = δΔψ[j]/k
-        δΔϵj = δΔϵ[j]/k
+        δΔψj = δΔψ[j] / k
+        δΔϵj = δΔϵ[j] / k
 
         # Converting CIP corrections to all conventions
-        δX_96[j], δY_96[j] = convert_cip_corr(m, iers1996,  tt_c[j], xin, yin, δXj, δYj)
+        δX_96[j], δY_96[j] = convert_cip_corr(m, iers1996, tt_c[j], xin, yin, δXj, δYj)
         δX_03[j], δY_03[j] = convert_cip_corr(m, iers2003a, tt_c[j], xin, yin, δXj, δYj)
         δX_10[j], δY_10[j] = convert_cip_corr(m, iers2010a, tt_c[j], xin, yin, δXj, δYj)
 
         # Convert nutation corrections to all conventions
-        δΔψ_96[j], δΔϵ_96[j] = convert_nut_corr(m, iers1996,  tt_c[j], δX_96[j], δY_96[j], δΔψj, δΔϵj)
+        δΔψ_96[j], δΔϵ_96[j] = convert_nut_corr(m, iers1996, tt_c[j], δX_96[j], δY_96[j], δΔψj, δΔϵj)
         δΔψ_03[j], δΔϵ_03[j] = convert_nut_corr(m, iers2003a, tt_c[j], δX_03[j], δY_03[j], δΔψj, δΔϵj)
         δΔψ_10[j], δΔϵ_10[j] = convert_nut_corr(m, iers2010a, tt_c[j], δX_10[j], δY_10[j], δΔψj, δΔϵj)
 
     end
-    
-    IERS_EOP_DATA.nut1996 = NutationCorrections(δX_96*k, δY_96*k, δΔψ_96*k, δΔϵ_96*k)
-    IERS_EOP_DATA.nut2003 = NutationCorrections(δX_03*k, δY_03*k, δΔψ_03*k, δΔϵ_03*k)
-    IERS_EOP_DATA.nut2010 = NutationCorrections(δX_10*k, δY_10*k, δΔψ_10*k, δΔϵ_10*k)
-    
+
+    IERS_EOP_DATA.nut1996 = NutationCorrections(δX_96 * k, δY_96 * k, δΔψ_96 * k, δΔϵ_96 * k)
+    IERS_EOP_DATA.nut2003 = NutationCorrections(δX_03 * k, δY_03 * k, δΔψ_03 * k, δΔϵ_03 * k)
+    IERS_EOP_DATA.nut2010 = NutationCorrections(δX_10 * k, δY_10 * k, δΔψ_10 * k, δΔϵ_10 * k)
+
     nothing
 
 end
@@ -142,21 +142,21 @@ function convert_cip_corr(::IERSModel, mout::IERSModel, tt_c, xin, yin, δX, δY
 
     δX_out = xin - xout + δX
     δY_out = yin - yout + δY
-    
+
     return δX_out, δY_out
 
 end
 
-function convert_cip_corr(::M, ::M, tt_c, x, y, δX, δY) where M <: IERSModel
+function convert_cip_corr(::M, ::M, tt_c, x, y, δX, δY) where {M<:IERSModel}
     return δX, δY
-end 
+end
 
 
 function convert_nut_corr(::IERSModel, ::IERSModel, tt_c, δX, δY, δΔψ, δΔϵ)
     return δcip_to_δnut(iers2010a, tt_c, δX, δY)
 end
 
-function convert_nut_corr(::M, ::M, tt_c, δX, δY, δΔψ, δΔϵ) where M <: IERSModel
+function convert_nut_corr(::M, ::M, tt_c, δX, δY, δΔψ, δΔϵ) where {M<:IERSModel}
     return δΔψ, δΔϵ
 end
 
@@ -171,12 +171,12 @@ Read Earth Orientation Parameters (EOP) from a dedicated JSMD `.eop.dat` file.
     retrieval of the relevant EOP data. 
 """
 function eop_read_data(filename)
-    
+
     if !endswith(filename, "eop.dat")
         throw(
             ArgumentError(
-                "EOP reader support only '.eop.dat' files! Please prepare " * 
-                "the data with \'eop_generate_from_csv\' and retry."
+                "EOP reader support only '.eop.dat' files! Please prepare " *
+                "the data with \'eop_generate_from_csv\' or \'eop_generate_from_txt\' and retry."
             )
         )
     end
@@ -186,15 +186,15 @@ function eop_read_data(filename)
 
     # Retrieve UT1-UTC 
     Δut1 = @view(data[:, 4])
-    
+
     # Convert UTC days to TT seconds
     days_utc = @view(data[:, 1])
-    days_tai = map(t->Tempo.utc2tai(Tempo.DJ2000, t)[2], days_utc)
-    days_tt  = days_tai .+ Tempo.OFFSET_TAI_TT/Tempo.DAY2SEC
+    days_tai = map(t -> Tempo.utc2tai(Tempo.DJ2000, t)[2], days_utc)
+    days_tt = days_tai .+ Tempo.OFFSET_TAI_TT / Tempo.DAY2SEC
 
     # Compute UT1-TT, in seconds
-    sec_ut1 = days_utc*Tempo.DAY2SEC + Δut1
-    ut1_tt = sec_ut1 - days_tt*Tempo.DAY2SEC
+    sec_ut1 = days_utc * Tempo.DAY2SEC + Δut1
+    ut1_tt = sec_ut1 - days_tt * Tempo.DAY2SEC
 
     # Retrieve other quantities
     xp = @view(data[:, 2])