Merge pull request #36 from EarthSciML/esmlv010

Upgrade to EarthSciMLBase.jl v0.10.0 and Update CI and Docs

.github/dependabot.yml

@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/CI.yml

@@ -28,11 +28,6 @@ jobs:
           - ubuntu-latest
         arch:
           - x64
-        include:
-          - version: 'nightly'
-            os: ubuntu-latest
-            arch: x64
-            experimental: true
     steps:
       - uses: actions/checkout@v3
       - uses: julia-actions/setup-julia@v1

.github/workflows/CompatHelper.yml

@@ -13,4 +13,4 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
-        run: julia -e 'using CompatHelper; CompatHelper.main()'
+        run: julia -e 'using CompatHelper; CompatHelper.main(; subdirs=["", "docs"])'

.github/workflows/cla.yml

@@ -14,7 +14,7 @@ jobs:
         # Pin to a specific version - this third-party action uses a personal access token
         uses: cla-assistant/github-action@948230deb0d44dd38957592f08c6bd934d96d0cf
         env:
-          GITHUB_TOKEN: ${{ secrets.CLA_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PERSONAL_ACCESS_TOKEN : ${{ secrets.CLA_PERSONAL_ACCESS_TOKEN }}
         with:
           # Signatures are stored in https://github.com/EarthSciML/cla

Project.toml

@@ -1,7 +1,7 @@
 name = "EarthSciData"
 uuid = "a293c155-435f-439d-9c11-a083b6b47337"
 authors = ["EarthSciML Authors"]
-version = "0.4.4"
+version = "0.5.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
@@ -24,8 +24,8 @@ AllocCheck = "0.1"
 DocStringExtensions = "0.9"
 DifferentialEquations = "7"
 Downloads = "1"
-EarthSciMLBase = "0.5, 0.6, 0.8"
-Interpolations = "0.14, 0.15"
+EarthSciMLBase = "0.10"
+Interpolations = "0.15"
 LaTeXStrings = "1"
 Latexify = "0.11, 0.12, 0.13, 0.14, 0.15, 0.16"
 ModelingToolkit = "8"

docs/Project.toml

@@ -8,3 +8,11 @@ MethodOfLines = "94925ecb-adb7-4558-8ed8-f975c56a0bf4"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
+
+[compat]
+DifferentialEquations = "7"
+DomainSets = "0.5, 0.6"
+MethodOfLines = "0.11"
+ModelingToolkit = "8"
+Unitful = "1"
+julia = "1.6"

docs/make.jl

@@ -12,10 +12,12 @@ makedocs(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://earthsciml.github.io/EarthSciData.jl",
         assets=String[],
+        repolink="https://github.com/EarthSciML/EarthSciData.jl"
     ),
     pages=[
         "Home" => "index.md",
         "GEOS-FP" => "geosfp.md",
+        "API" => "api.md",
     ],
 )
 

docs/src/api.md

@@ -0,0 +1,6 @@
+```@index
+```
+
+```@autodocs
+Modules = [EarthSciData]
+```

docs/src/geosfp.md

@@ -1,44 +1,57 @@
 # Using data from GEOS-FP
 
-``` example 1
+This example demonstrates how to use the GEOS-FP data loader in the EarthSciML ecosystem. The GEOS-FP data loader is used to load data from the [GEOS-FP](https://gmao.gsfc.nasa.gov/GMAO_products/NRT_products.php) dataset.
+
+First, let's initialize some packages and set up the [GEOS-FP](@ref GEOSFP) equation system.
+
+```@example geosfp
 using EarthSciData, EarthSciMLBase
-using DomainSets, ModelingToolkit, MethodOfLines, DifferentialEquations
+using DomainSets, ModelingToolkit, MethodOfLines#, DifferentialEquations
 using Dates, Plots
 
 # Set up system
 @parameters t lev lon lat
-geosfp = GEOSFP{Float64}("4x5", t)
-
-struct Example <: EarthSciMLODESystem
-    sys
-    function Example(t; name)
-        @variables c(t) = 5.0
-        D = Differential(t)
-        new(ODESystem([D(c) ~ sin(lat * π / 180.0 * 6) + sin(lon * π / 180 * 6)], t, name=name))
-    end
+geosfp = GEOSFP("4x5", t)
+```
+
+We can see above the different variables that are available in the GEOS-FP dataset.
+
+The GEOS-FP equation system isn't an ordinary differential equation (ODE) system, so we can't run it by itself.
+To fix this, we create another equation system that is an ODE. 
+(We don't actually end up using this system for anything, it's just necessary to get the system to compile.)
+
+```@example geosfp
+function Example(t)
+    @variables c(t) = 5.0
+    D = Differential(t)
+    ODESystem([D(c) ~ sin(lat * π / 180.0 * 6) + sin(lon * π / 180 * 6)], t, name=:Docs₊Example)
 end
-@named examplesys = Example(t)
+examplesys = Example(t)
+```
+
+Now, let's couple these two systems together, and also add in advection and some information about the domain:
 
+```@example geosfp
 domain = DomainInfo(
     partialderivatives_lonlat2xymeters,
     constIC(0.0, t ∈ Interval(Dates.datetime2unix(DateTime(2022, 1, 1)), Dates.datetime2unix(DateTime(2022, 1, 3)))),
-    zerogradBC(lat ∈ Interval(-85.0f0, 85.0f0)),
-    periodicBC(lon ∈ Interval(-180.0f0, 175.0f0)),
-    zerogradBC(lev ∈ Interval(1.0f0, 10.0f0)),
+    zerogradBC(lat ∈ Interval(-80.0f0, 80.0f0)),
+    periodicBC(lon ∈ Interval(-180.0f0, 180.0f0)),
+    zerogradBC(lev ∈ Interval(1.0f0, 11.0f0)),
 )
 
-composed_sys = examplesys + domain + Advection() + geosfp;
+composed_sys = couple(examplesys, domain, geosfp)
 pde_sys = get_mtk(composed_sys)
+```
+
+Now, finally, we can run the simulation and plot the GEOS-FP wind fields in the result:
 
-# Solve
-discretization = MOLFiniteDifference([lat => 6, lon => 6, lev => 6], t, approx_order=2)
+```@example geosfp
+discretization = MOLFiniteDifference([lat => 10, lon => 10, lev => 10], t, approx_order=2)
 @time pdeprob = discretize(pde_sys, discretization)
 
-#@run pdesol = solve(pdeprob, Tsit5(), saveat=3600.0)
-@profview pdesol = solve(pdeprob, Tsit5(), saveat=36000.0)
-@time pdesol = solve(pdeprob, Tsit5(), saveat=3600.0)
+pdesol = solve(pdeprob, Tsit5(), saveat=3600.0)
 
-# Plot
 discrete_lon = pdesol[lon]
 discrete_lat = pdesol[lat]
 discrete_lev = pdesol[lev]
@@ -56,7 +69,7 @@ anim = @animate for k in 1:length(discrete_t)
             title="U")
     p3 = heatmap(discrete_lon, discrete_lat, sol_v[k, 1:end, 1:end, 2], clim=(minimum(sol_v[:, :, :, 2]), maximum(sol_v[:, :, :, 2])),
             title="V")
-    plot(p1, p2, p3, size=(1200, 700))
+    plot(p1, p2, p3, size=(800, 500))
 end
 gif(anim, "animation.gif", fps = 8)
 ```

docs/src/index.md

@@ -6,9 +6,81 @@ CurrentModule = EarthSciData
 
 Documentation for [EarthSciData](https://github.com/EarthSciML/EarthSciData.jl).
 
-```@index
+## Installation
+
+```julia
+using Pkg
+Pkg.add("EarthSciMLData")
 ```
 
-```@autodocs
-Modules = [EarthSciData]
+## Feature Summary
+
+This package contains data loaders for use with the [EarthSciML](https://earthsci.dev/) ecosystem.
+
+## Feature List
+
+* Loader for [GEOS-FP](https://gmao.gsfc.nasa.gov/GMAO_products/NRT_products.php) data.
+* Loader for [2016 NEI](https://gaftp.epa.gov/Air/) emissions data.
+
+## Contributing
+
+* Please refer to the
+  [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
+  for guidance on PRs, issues, and other matters relating to contributing.
+
+## Reproducibility
+```@raw html
+<details><summary>The documentation of this EarthSciML package was built using these direct dependencies,</summary>
+```
+```@example
+using Pkg # hide
+Pkg.status() # hide
+```
+```@raw html
+</details>
+```
+```@raw html
+<details><summary>and using this machine and Julia version.</summary>
+```
+```@example
+using InteractiveUtils # hide
+versioninfo() # hide
+```
+```@raw html
+</details>
+```
+```@raw html
+<details><summary>A more complete overview of all dependencies and their versions is also provided.</summary>
+```
+```@example
+using Pkg # hide
+Pkg.status(;mode = PKGMODE_MANIFEST) # hide
+```
+```@raw html
+</details>
+```
+```@raw html
+You can also download the 
+<a href="
+```
+```@eval
+using TOML
+using Markdown
+version = TOML.parse(read("../../Project.toml",String))["version"]
+name = TOML.parse(read("../../Project.toml",String))["name"]
+link = Markdown.MD("https://github.com/EarthSciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Manifest.toml")
+```
+```@raw html
+">manifest</a> file and the
+<a href="
+```
+```@eval
+using TOML
+using Markdown
+version = TOML.parse(read("../../Project.toml",String))["version"]
+name = TOML.parse(read("../../Project.toml",String))["name"]
+link = Markdown.MD("https://github.com/EarthSciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Project.toml")
 ```
+```@raw html
+">project</a> file.
+```

src/geosfp.jl

@@ -176,12 +176,12 @@ Domain options (as of 2022-01-30):
 domain. For example if we want to perform a 2D simulation with a vertical dimension,
 we can set `coord_defaults = Dict(:lev => 1)`.
 
+`dtype` represents the desired data type of the interpolated values. The native data type
+for this dataset is Float32.
+
 See http://geoschemdata.wustl.edu/ExtData/ for current options.
 """
-struct GEOSFP{T} <: EarthSciMLODESystem
-    filesets::Dict{String,GEOSFPFileSet}
-    sys::ODESystem
-    function GEOSFP{T}(domain, t; coord_defaults=Dict{Symbol,Number}()) where {T<:Number}
+    function GEOSFP(domain, t; coord_defaults=Dict{Symbol,Number}(), dtype=Float32)
         filesets = Dict{String,GEOSFPFileSet}(
             "A1" => GEOSFPFileSet(domain, "A1"),
             "A3cld" => GEOSFPFileSet(domain, "A3cld"),
@@ -194,7 +194,7 @@ struct GEOSFP{T} <: EarthSciMLODESystem
         eqs = []
         for (filename, fs) in filesets
             for varname ∈ varnames(fs, sample_time)
-                itp = DataSetInterpolator{T}(fs, varname, sample_time)
+                itp = DataSetInterpolator{dtype}(fs, varname, sample_time)
                 dims = dimnames(itp, sample_time)
                 coords = Num[]
                 for dim ∈ dims
@@ -209,21 +209,18 @@ struct GEOSFP{T} <: EarthSciMLODESystem
                 push!(eqs, create_interp_equation(itp, filename, t, sample_time, coords))
             end
         end
-        sys = ODESystem(eqs, t, name=:GEOSFP)
-
-        new(filesets, sys)
-    end
+        ODESystem(eqs, t, name=:EarthSciData₊GEOSFP)
 end
 
-function Base.:(+)(mw::EarthSciMLBase.MeanWind, g::GEOSFP)::ComposedEarthSciMLSystem
-    eqs = [mw.sys.v_lon ~ g.sys.A3dyn₊U]
+@parameters t # TODO(CT) Remove when updating to MTK v9.
+EarthSciMLBase.register_coupling(EarthSciMLBase.MeanWind(t), GEOSFP("4x5", t)) do mw, g
+    eqs = [mw.v_lon ~ g.A3dyn₊U]
     # Only add the number of dimensions present in the mean wind system.
-    length(states(mw.sys)) > 1 ? push!(eqs, mw.sys.v_lat ~ g.sys.A3dyn₊V) : nothing
-    length(states(mw.sys)) > 2 ? push!(eqs, mw.sys.v_lev ~ g.sys.A3dyn₊OMEGA) : nothing
+    length(states(mw.sys)) > 1 ? push!(eqs, mw.v_lat ~ g.A3dyn₊V) : nothing
+    length(states(mw.sys)) > 2 ? push!(eqs, mw.v_lev ~ g.A3dyn₊OMEGA) : nothing
 
-    ComposedEarthSciMLSystem(AbstractEarthSciMLSystem[ConnectorSystem(
+    ConnectorSystem(
             eqs,
             mw, g,
-        )], nothing, [(sys) -> prune!(sys, "GEOSFP₊")]) # Prune extra data interpolators before running to save cost.
-end
-Base.:(+)(g::GEOSFP, mw::EarthSciMLBase.MeanWind)::ComposedEarthSciMLSystem = mw + g
+    )
+end

src/load.jl

@@ -149,10 +149,6 @@ function Base.show(io::IO, itp::DataSetInterpolator)
     print(io, "DataSetInterpolator{$(typeof(itp.fs)), $(itp.varname)}")
 end
 
-Latexify.@latexrecipe function f(itp::EarthSciData.DataSetInterpolator)
-    return "$(typeof(itp.fs))ₓ$(itp.varname)_interp"
-end
-
 """ Return the units of the data. """
 ModelingToolkit.get_unit(itp::DataSetInterpolator) = itp.data1.units
 
@@ -293,4 +289,8 @@ function create_interp_equation(itp::DataSetInterpolator, filename, t, sample_ti
     else
         error("Unexpected number of coordinates: $(length(coords))")
     end
+end
+
+Latexify.@latexrecipe function f(itp::EarthSciData.DataSetInterpolator)
+    return "$(typeof(itp.fs))ₓ$(itp.varname)_interp"
 end

src/nei2016monthly.jl

@@ -148,6 +148,9 @@ values of the given `spatial_ref`,
 and the `lev` represents the variable for the vertical grid level.
 Δx and Δy must be in units of meters, and x and y must be in the same units as `spatial_ref`.
 
+`dtype` represents the desired data type of the interpolated values. The native data type
+for this dataset is Float32.
+
 NOTE: This is an interpolator that returns the emissions value of the nearest grid cell 
 center for the underlying emissions grid, so it may not exactly conserve the total 
 emissions mass, especially if the simulation grid is coarser than the emissions grid.
@@ -160,19 +163,14 @@ using EarthSciData, ModelingToolkit, Unitful
 emis = NEI2016MonthlyEmis{Float32}("mrggrid_withbeis_withrwc", t, lon, lat, lev, Δz)
 ```
 """
-struct NEI2016MonthlyEmis{T} <: EarthSciMLODESystem
-    fileset::NEI2016MonthlyEmisFileSet
-    sys::ODESystem
-    function NEI2016MonthlyEmis{T}(sector, t, x, y, lev, Δz; spatial_ref="EPSG:4326") where T<:Number
-        fs = NEI2016MonthlyEmisFileSet(sector)
-        sample_time = DateTime(2016, 5, 1) # Dummy time to get variable names and dimensions from data.
-        eqs = []
-        @assert ModelingToolkit.get_unit(Δz) == u"m" "Δz must be in units of meters."
-        for varname ∈ varnames(fs, sample_time)
-            itp = DataSetInterpolator{T}(fs, varname, sample_time; spatial_ref)
-            push!(eqs, create_interp_equation(itp, sector, t, sample_time, [x, y, lev], 1/Δz))
-        end
-        sys = ODESystem(eqs, t; name=:NEI2016MonthlyEmis)
-        new(fs, sys)
+function NEI2016MonthlyEmis(sector, t, x, y, lev, Δz; spatial_ref="EPSG:4326", dtype=Float32)
+    fs = NEI2016MonthlyEmisFileSet(sector)
+    sample_time = DateTime(2016, 5, 1) # Dummy time to get variable names and dimensions from data.
+    eqs = []
+    @assert ModelingToolkit.get_unit(Δz) == u"m" "Δz must be in units of meters."
+    for varname ∈ varnames(fs, sample_time)
+        itp = DataSetInterpolator{dtype}(fs, varname, sample_time; spatial_ref)
+        push!(eqs, create_interp_equation(itp, sector, t, sample_time, [x, y, lev], 1/Δz))
     end
+    ODESystem(eqs, t; name=:NEI2016MonthlyEmis)
 end