Change some docstrings that were not updated to reflect the function …

…signature (#138) * change some docstrings * typo * some more changes * a small bugfix * Update ECCO_restoring.jl --------- Co-authored-by: Navid C. Constantinou <[email protected]>
CliMA · Nov 8, 2024 · 9c858b0 · 9c858b0
1 parent 3ca5495
commit 9c858b0
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 27 deletions.
diff --git a/src/DataWrangling/ECCO/ECCO.jl b/src/DataWrangling/ECCO/ECCO.jl
@@ -118,18 +118,13 @@ function empty_ECCO_field(metadata::ECCOMetadata;
 end
 
 """
-    ECCO_field(variable_name;
+    ECCO_field(metadata::ECCOMetadata;
                architecture = CPU(),
-               horizontal_halo = (1, 1),
-               user_data = nothing,
-               url = ecco_urls[variable_name],
-               short_name = ecco_short_names[variable_name])
-
-Retrieve the ECCO field corresponding to `variable_name`. 
-The data is either:
-(1) retrieved from `filename`,
-(2) dowloaded from `url` if `filename` does not exists,
-(3) filled from `user_data` if `user_data` is provided.
+               horizontal_halo = (3, 3))
+
+Retrieve the ecco field corresponding to `metadata`. 
+The data is loaded from `filename` on `architecture` with `horizontal_halo`
+in the x and y direction. The halo in the z-direction is one.
 """
 function ECCO_field(metadata::ECCOMetadata;
                     architecture = CPU(),
@@ -187,21 +182,20 @@ ECCO_field(var_name::Symbol; kw...) = ECCO_field(ECCOMetadata(var_name); kw...)
                          mask = ECCO_mask(architecture),
                          maxiter = Inf)
     
-Retrieve the ECCO field corresponding to `variable_name` inpainted to fill all the
-missing values in the original dataset.
+    
+Retrieve the ECCO field corresponding to `metadata` inpainted to fill all the missing values in the original dataset.
 
 Arguments:
 ==========
 
-- `variable_name`: the variable name corresponding to the Dataset.
+- `metadata`: the metadata corresponding to the dataset.
 
 Keyword Arguments:
 ==================
 
 - `architecture`: either `CPU()` or `GPU()`.
-- `mask`: the mask used to inpaint the field (see `inpaint_mask!`).
-- `maxiter`: the maximum number of iterations to inpaint the field (see `inpaint_mask!`).
-
+- `mask`: the mask used to inpaint the field, see [`inpaint_mask!`](@ref).
+- `inpainting`: the inpainting algorithm, see [`inpaint_mask!`](@ref). Default: `NearestNeighborInpainting(Inf)`.
 """
 function inpainted_ECCO_field(metadata::ECCOMetadata; 
                               architecture = CPU(),

diff --git a/src/DataWrangling/ECCO/ECCO_restoring.jl b/src/DataWrangling/ECCO/ECCO_restoring.jl
@@ -108,15 +108,17 @@ end
 Create a field time series object for ECCO data.
 
 # Arguments:
+============
 - metadata: An ECCOMetadata object containing information about the ECCO dataset.
 
 # Keyword Arguments:
+====================
 - architecture: The architecture to use for computations (default: CPU()).
 - time_indices_in_memory: The number of time indices to keep in memory (default: 2).
 - time_indexing: The time indexing scheme to use (default: Cyclical()).
-- `inpainting`: The inpainting algorithm to use for ECCO interpolation. For the moment, the only option is `NearestNeighborInpainting(maxiter)`, 
+- `inpainting`: The inpainting algorithm to use for ECCO interpolation. For the moment, the only option is `NearestNeighborInpainting(maxiter)`.
                 where an average of the valid surrounding values is used `maxiter` times.
-- grid: if not a `nothing`, the ECCO data is directly interpolated on the `grid`,
+- grid: if not a `nothing`, the ECCO data is directly interpolated on the `grid`.
 """
 function ECCO_field_time_series(metadata::ECCOMetadata;	
                                 architecture = CPU(),	
@@ -249,16 +251,23 @@ end
 @inline get_ECCO_variable(::Val{false}, ECCO_fts, i, j, k, ECCO_grid, grid, time) = @inbounds ECCO_fts[i, j, k, time]
 
 """
-    ECCORestoring(variable_name::Symbol, [architecture = CPU()]; 
-                  version = ECCO4Monthly(),
+    ECCORestoring(variable_name::Symbol, [architecture = CPU()];
+                  version=ECCO4Monthly(), 
                   dates = all_ECCO_dates(version), 
-                  time_indices_in_memory = 2, # Not more than this if we want to use GPU!
+                  time_indices_in_memory = 2, 
                   time_indexing = Cyclical(),
                   mask = 1,
                   rate = 1,
                   grid = nothing,
-                  inpainting_iterations = prod(size(metadata)))
+                  inpainting = NearestNeighborInpainting(prod(size(metadata))))
+
 Create a restoring forcing term that restores to values stored in an ECCO field time series.
+The restoring is applied as a forcing on the right hand side of the evolution equations calculated as
+```math
+F = mask ⋅ rate ⋅ (ECCO_variable - simulation_variable[i, j, k])
+```
+where ECCO_variable is linearly interpolated in space and time from the ECCO dataset of choice to the 
+simulation grid and time.
 
 # Positional Arguments (order does not matter):
 ===============================================
@@ -281,8 +290,9 @@ Create a restoring forcing term that restores to values stored in an ECCO field
 - `time_indexing`: The time indexing scheme for the field time series≥
 - `mask`: The mask value. Can be a function of `(x, y, z, time)`, an array or a number
 - `rate`: The restoring rate in s⁻¹.
-- `time_indices_in_memory = 2, # Not more than this if we want to use GPU!
-- `inpainting_iterations`: maximum number of iterations for the inpainting algorithm. (defaults to `prod(size(metadata))`)
+- `time_indices_in_memory:` how many time instances are loaded in memory. The remaining are loaded lazily.
+- `grid`: if not a `nothing`, the ECCO data is directly interpolated on the `grid`.
+- `inpainting`: inpainting algorithm, see [`inpaint_mask!`](@ref). Defaults to `NearestNeighborInpainting(Inf)`.
 
 It is possible to also pass an `ECCOMetadata` type as the first argument without the need for the 
 `variable_name` argument and the `version` and `dates` keyword arguments.
@@ -306,7 +316,7 @@ function ECCORestoring(metadata::ECCOMetadata;
                        mask = 1,
                        rate = 1,
                        grid = nothing,
-                       inpainting = NearestNeighborInpainting(prod(size(metadata))))
+                       inpainting = NearestNeighborInpainting(Inf))
 
     ECCO_fts  = ECCO_field_time_series(metadata; grid, architecture, time_indices_in_memory, time_indexing, inpainting)                  
     ECCO_grid = ECCO_fts.grid
@@ -326,4 +336,4 @@ Base.show(io::IO, p::ECCORestoring) =
               "├── mask: ", summary(p.mask), '\n',
               "└── grid: ", summary(p.grid))
 
-regularize_forcing(forcing::ECCORestoring, field, field_name, model_field_names) = forcing
+regularize_forcing(forcing::ECCORestoring, field, field_name, model_field_names) = forcing