Merge pull request JuliaClimate#10 from JuliaClimate/docsEtc-gf01

streamline and improve docs, examples, files
gaelforget · Feb 11, 2020 · 10da698 · 10da698
2 parents d2a79e7 + e944e08
commit 10da698
Show file tree

Hide file tree

Showing 17 changed files with 370 additions and 384 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "IndividualDisplacements"
 uuid = "b92f0c32-5b7e-11e9-1d7b-238b2da8b0e6"
 authors = ["gaelforget <gforget@mit.edu>"]
-version = "0.1.5"
+version = "0.1.6"
 
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"

diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaClimate.github.io/IndividualDisplacements.jl/dev)
 [![DOI](https://zenodo.org/badge/208676176.svg)](https://zenodo.org/badge/latestdoi/208676176)
 
-**IndividualDisplacements.jl** computes point displacements over a gridded domain. It is geared towards the analysis of Climate, Ocean, etc models (`Arakawa C-grids` are natively supported) and material transports within the Earth System (e.g. simulation of plastics or planktons over the Global Ocean; dusts or chemicals in the Atmosphere). 
+**IndividualDisplacements.jl** computes point displacements over a gridded domain. It is geared towards the analysis of Climate, Ocean, etc models (`Arakawa C-grids` are natively supported) and the simulation of material transports within the Earth System (e.g. plastics or planktons in the Ocean; dusts or chemicals in the Atmosphere). 
 
 Inter-operability with popular climate model grids via [MeshArrays.jl](https://github.com/JuliaClimate/MeshArrays.jl) is an important aspect. The package can read and write individual displacement collection files, including those generated by the [MIT general circulation model](https://mitgcm.readthedocs.io/en/latest/?badge=latest). `IndividualDisplacements`'s initial test suite is based on global ocean model simulations called [ECCO (v4r2)](https://eccov4.readthedocs.io/en/latest/) and [CBIOMES (alpha)](https://cbiomes.readthedocs.io/en/latest/) (see [Forget et al. 2015](https://doi.org/10.5194/gmd-8-3071-2015)).
 
@@ -17,32 +17,20 @@ Pkg.add("IndividualDisplacements")
 Pkg.test("IndividualDisplacements")
 ```
 
-![alt-text-1](examples/ex_2_mitgcm.png "From MITgcm")         |  ![alt-text-2](examples/ex_1_mitgcm.png "From MITgcm")
-:------------------------------:|:---------------------------------:
-![alt-text-3](examples/PeriodicDomainRandomFlow.png "Computed in Julia")  |  ![alt-text-4](examples/LatLonCap300mDepth.png "Computed in Julia")
+<img src="examples/ex_1_mitgcm.png" width="50%"> <img src="examples/LatLonCap300mDepth.png" width="40%">
 
 ### Example
 
-This example reproduces an individual trajectory originally computed by the `MITgcm` fortran implementation:
+This example reproduces an individual trajectory computed by `MITgcm` but using `Julia`:
 
 ```
-#import software
 using IndividualDisplacements
-p=dirname(pathof(IndividualDisplacements)); 
-cd(p*"/../examples")
 
-#download data
 if !isdir("flt_example")
     run(`git clone https://github.com/gaelforget/flt_example`)
 end
 
-#run example
-(df,pl)=IndividualDisplacements.ex_2()
-
-#display result
-display(pl)
+(df,ref,sol)=IndividualDisplacements.example2()
 ```
 
 ![alt-text-5](examples/ex_2.png "Computed in Julia")
-
-![alt-text-6](examples/SolidBodyRotation.png "Unit test")
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,6 +1,12 @@
 # IndividualDisplacements.jl
 
-**IndividualDisplacements.jl** computes elementary point displacements over a gridded model domain. It can also read / write them from / to file. A typical application is the simulation and analysis of materials drifting or moving over the Global Ocean (e.g. plastics or planktons) or Atmosphere (e.g. dust or chemicals). Inter-operability with popular climate model grids and [MeshArrays.jl](https://github.com/JuliaClimate/MeshArrays.jl) is an important prospect. `IndividualDisplacements.jl ` was initially designed in relation to [MITgcm](https://mitgcm.readthedocs.io/en/latest/?badge=latest), [ECCOv4](https://eccov4.readthedocs.io/en/latest/) ([Forget et al. 2015](https://doi.org/10.5194/gmd-8-3071-2015)), and [CBIOMES](https://cbiomes.readthedocs.io/en/latest/) model simulations.
+**IndividualDisplacements.jl** computes elementary point displacements over a gridded Earth domain (e.g. a climate model C-grid). A typical application is the simulation and analysis of materials moving through atmospheric flows (e.g. dust or chemicals) or oceanic flows (e.g. plastics or planktons).
+
+Inter-operability with popular climate model grids and their representation in [MeshArrays.jl](https://github.com/JuliaClimate/MeshArrays.jl) is a central element. The package can also read and plot trajectory simulation output from e.g. the [MITgcm](https://mitgcm.readthedocs.io/en/latest/?badge=latest). It was originally developed using [ECCOv4](https://eccov4.readthedocs.io/en/latest/) and [CBIOMES](https://cbiomes.readthedocs.io/en/latest/) ocean model simulations ([Forget et al. 2015](https://doi.org/10.5194/gmd-8-3071-2015)).
+
+The `VelComp!` and `VelComp` functions compute the velocity of tracked points. `tests/runtests.jl` uses solid body rotation as a benchmark (see below).
+
+<img src="https://github.com/JuliaClimate/IndividualDisplacements.jl/blob/master/examples/SolidBodyRotation.png" width="50%">
 
 ## API Guide
 

diff --git a/examples/body_rotation_test.jl b/examples/body_rotation_test.jl
@@ -21,7 +21,7 @@
 
 # ## 1. import software and `pkg/flt` trajectories
 
-using IndividualDisplacements, MeshArrays, Plots, DifferentialEquations
+using IndividualDisplacements, MeshArrays, OrdinaryDiffEq, Plots
 
 # ## 2. Define gridded variables as `MeshArray`s
 
@@ -65,15 +65,13 @@ du=fill(0.0,2);
 
 # ## 4. solve through time using DifferentialEquations.jl
 
-using DifferentialEquations
 tspan = (0.0,nSteps*3600.0)
 prob = ODEProblem(IndividualDisplacements.VelComp,uInit,tspan,uvetc)
 sol = solve(prob,Tsit5(),reltol=1e-8,abstol=1e-8)
 sol[1:4]
 
 # ## 5. visualize trajectory
 
-using Plots
 Plots.plot(sol[1,:],sol[2,:],linewidth=5,title="Solid body rotation example",
      xaxis="lon",yaxis="lat",label="Julia Solution") # legend=false
 #Plots.savefig("SolidBodyRotation.png")

diff --git a/examples/ex_2_more.jl b/examples/ex_2_more.jl
@@ -18,21 +18,21 @@
 # - [x] read gridded output + `float_trajectory*data` => `uvetc` dictionnary.
 # - [x] recompute `u,v` from gridded output
 # - [x] compare with `u,v` from `float_traj*data`
-# - [x] solve for float trajectory with `DifferentialEquations.jl`
+# - [x] solve for trajectory with `OrdinaryDiffEq.jl` (part of `DifferentialEquations.jl`)
 #
 # _Notes:_ For documentation see <https://gaelforget.github.io/MeshArrays.jl/stable/>, <https://docs.juliadiffeq.org/latest/solvers/ode_solve.html> and <https://en.wikipedia.org/wiki/Displacement_(vector)>
 
 # ## 1. import software
 
-using IndividualDisplacements, MeshArrays, DifferentialEquations, Plots
+using IndividualDisplacements, MeshArrays, OrdinaryDiffEq, Plots
 p=dirname(pathof(IndividualDisplacements))
 include(joinpath(p,"plot_pyplot.jl"))
 
 # ## 2. reload trajectories from `MITgcm/pkg/flt` 
 
 dirIn="flt_example/"
 prec=Float32
-df=IndividualDisplacements.ReadDisplacements(dirIn,prec)
+df=ReadDisplacements(dirIn,prec) #function exported by IndividualDisplacements
 PyPlot.figure(); PlotBasic(df,300,100000.0)
 
 # ## 3. Read gridded variables via `MeshArrays.jl`
@@ -120,8 +120,8 @@ colorbar()
 # ## 6. Recompute displacements from gridded flow fields
 
 # +
-comp_vel=IndividualDisplacements.VelComp
-get_vel=IndividualDisplacements.VelCopy
+comp_vel=VelComp #function exported by IndividualDisplacements
+get_vel=VelCopy #function exported by IndividualDisplacements
 
 uInit=[tmp[1,:lon];tmp[1,:lat]]./uvetc["dx"]
 nSteps=Int32(tmp[end,:time]/3600)-2
@@ -180,9 +180,15 @@ Plots.plot!(refv)
 
 # ## 6. Recompute trajectories from gridded flow fields
 #
-# Solve through time using `DifferentialEquations.jl`
+# Solve through time using `OrdinaryDiffEq.jl` with 
+#
+# - `comp_vel` is the function computing `du/dt`
+# - `uInit` is the initial condition `u @ tspan[1]`
+# - `tspan` is the time interval
+# - `uvetc` are parameters for `comp_vel`
+# - `Tsit5` is the time-stepping scheme
+# - `reltol` and `abstol` are tolerance parameters
 
-using DifferentialEquations
 tspan = (0.0,nSteps*3600.0)
 #prob = ODEProblem(get_vel,uInit,tspan,tmp)
 prob = ODEProblem(comp_vel,uInit,tspan,uvetc)
@@ -204,7 +210,6 @@ for i=1:nSteps-1
 end
 ref=ref./uvetc["dx"]
 
-using Plots
 Plots.plot(sol[1,:],sol[2,:],linewidth=5,title="Using Recomputed Velocities",
      xaxis="lon",yaxis="lat",label="Julia Solution") # legend=false
 Plots.plot!(ref[1,:],ref[2,:],lw=3,ls=:dash,label="MITgcm Solution")

diff --git a/examples/flt_xmpl_fleet.jl b/examples/flt_xmpl_fleet.jl
@@ -19,7 +19,8 @@
 
 # ## 1. import software
 
-using IndividualDisplacements, MeshArrays, DifferentialEquations, Plots, Statistics
+using IndividualDisplacements, MeshArrays, OrdinaryDiffEq
+using Plots, Statistics, MITgcmTools, DataFrames
 p=dirname(pathof(IndividualDisplacements))
 include(joinpath(p,"plot_pyplot.jl"))
 
@@ -120,7 +121,6 @@ Plots.plot!(tmpv)
 
 # ## 5. Solve through time using `DifferentialEquations.jl`
 
-using DifferentialEquations
 tspan = (0.0,nSteps*3600.0)
 #prob = ODEProblem(get_vel,uInit,tspan,tmp)
 prob = ODEProblem(comp_vel,uInit,tspan,uvetc)

diff --git a/examples/flt_xmpl_single.jl b/examples/flt_xmpl_single.jl
@@ -19,7 +19,7 @@
 
 # ## 1. import software
 
-using IndividualDisplacements, MeshArrays, DifferentialEquations, Plots, Statistics
+using IndividualDisplacements, MeshArrays, OrdinaryDiffEq, Plots, Statistics
 p=dirname(pathof(IndividualDisplacements)); include(joinpath(p,"plot_pyplot.jl"))
 
 # ## 2. Read gridded variables as `MeshArray`s
@@ -119,7 +119,6 @@ Plots.plot!(tmpv)
 
 # ## 5. Solve through time using `DifferentialEquations.jl`
 
-using DifferentialEquations
 tspan = (0.0,nSteps*3600.0)
 #prob = ODEProblem(get_vel,uInit,tspan,tmp)
 prob = ODEProblem(comp_vel,uInit,tspan,uvetc)

diff --git a/examples/global_ocean_fleet.jl b/examples/global_ocean_fleet.jl
@@ -19,8 +19,8 @@
 
 # ## 1. import software
 
-using IndividualDisplacements, MeshArrays, DifferentialEquations 
-using Plots, Statistics, Dierckx
+using IndividualDisplacements, MeshArrays, OrdinaryDiffEq 
+using Plots, Statistics, Dierckx, MAT
 p=dirname(pathof(IndividualDisplacements))
 include(joinpath(p,"plot_pyplot.jl"))
 
@@ -42,7 +42,6 @@ GridVariables=Dict("XC" => read(mygrid.path*"XC.latlon.data",MeshArray(mygrid,Fl
 # Read velocity fields as `MeshArray`s.
 
 # +
-using MAT
 file = matopen(mygrid.path*"uv_lonlat.mat")
 u=read(file, "u")
 v=read(file, "v")

diff --git a/examples/global_ocean_single.jl b/examples/global_ocean_single.jl
@@ -19,7 +19,8 @@
 
 # ## 1. import software
 
-using IndividualDisplacements, MeshArrays, DifferentialEquations, Plots, Statistics
+using IndividualDisplacements, MeshArrays, OrdinaryDiffEq
+using Plots, Statistics, MAT
 p=dirname(pathof(IndividualDisplacements))
 include(joinpath(p,"plot_pyplot.jl"))
 
@@ -41,7 +42,6 @@ GridVariables=Dict("XC" => read(mygrid.path*"XC.latlon.data",MeshArray(mygrid,Fl
 # Read velocity fields as `MeshArray`s.
 
 # +
-using MAT
 file = matopen(mygrid.path*"uv_lonlat.mat")
 u=read(file, "u")
 v=read(file, "v")
@@ -135,7 +135,6 @@ Plots.plot!(tmpv)
 
 # ## 5. Solve through time using `DifferentialEquations.jl`
 
-using DifferentialEquations
 tspan = (0.0,nSteps*3600.0)
 #prob = ODEProblem(get_vel,uInit,tspan,tmp)
 prob = ODEProblem(comp_vel,uInit,tspan,uvetc)

diff --git a/src/IndividualDisplacements.jl b/src/IndividualDisplacements.jl
@@ -2,15 +2,16 @@ module IndividualDisplacements
 
 greet() = print("Get ready for IndividualDisplacements!")
 
-include("ReadIndDisp.jl")
-include("VelocityIndDisp.jl")
+using MeshArrays, OrdinaryDiffEq, StatsBase, DataFrames, Random
+
+include("compute.jl")
+include("read.jl")
 include("examples.jl")
 
-export VelComp, VelComp!, VelCopy, ReadGriddedFields, ReadDisplacements
+export VelComp, VelComp!, VelCopy, ReadDisplacements
 
 #include("plot_pyplot.jl")
 #include("plot_makie.jl")
-
 #export PlotBasic, PlotMapProj, PlotMakie
 
 end # module