Support for CROCO 3D velocities

[erikvansebille]

This PR implements support for 3D velocities in CROCO (and potentially also ROMS, but not tested). Users can simply call FieldSet.from_croco() and provide the w field from CROCO output in their variables list and call the AdvectionRK4_3D kernel. Under the hood, Parcels will then replace the kernel with AdvectionRK4_3D_CROCO, which works slightly different from the normal 3D advection kernel because it converts the vertical velocity in sigma-units.

In particular, the following algorithm is used (note that the RK4 version is slightly more complex than this Euler-Forward version, but the idea is identical)

    # calculate local sigma level of particle, by scaling depth by local ocean depth H
    sigma = particle.depth / fieldset.H[time, particle.depth, particle.lat, particle.lon]

    (u, v, w) = fieldset.UVW[time, particle.depth, particle.lat, particle.lon, particle]  

    # scaling the w with the sigma level of the particle
    w1 *= sigma 

    lon_new = particle.lon + u*particle.dt
    lat_new = particle.lat + v*particle.dt

    # calculating new sigma level
    sigma_new = sigma + w/fieldset.H[time, particle.depth, particle.lat, particle.lon]*particle.dt 
    
    # Converting back from sigma to depth, at _new_ location
    depth_new = sigma_new * fieldset.H[time, particle.depth, lat_new, lon_new]  

We have tested this algorithm on an idealised setup (created by @vesnaber) of a purely zonal flow over a sloping bottom. Particles indeed stay on their depth levels (so cross sigma-levels) as expected, with this algorithm. So we think this is an appropriate scheme.

To make this work under the hood, we had to adapt Parcels to convert from particle depth (in m) to sigma-coordinates in Field interpolations. In a call such as fieldset.U[time, particle.depth, particle.lat, particle.lon], the particle.depth will thus under-the-hood be converted to sigma (= particle.depth / fieldset.H[time, particle.depth, particle.lat, particle.lon]).

Todo before this PR can be merged

• Further implement FieldSet.from_croco() for seamless use
• Test 2D CROCO surface flow too (so without providing w field)
• Create tutorial how to use Parcels with CROCO
• Support for sampling of individual Fields (not velocities)
• Consider retiring (but perhaps in another Issue/PR) the RectilinearSGrid and CurvilinearSGrid classes, as this new approach to sigma-grids seems to be more robust
• Test the new algorithm in more realistic simulations

[codecov]

Codecov Report

Attention: Patch coverage is 66.01942% with 70 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
parcels/application_kernels/advection.py	19.04%	34 Missing ⚠️
parcels/fieldset.py	41.46%	23 Missing and 1 partial ⚠️
parcels/field.py	79.41%	7 Missing ⚠️
parcels/compilation/codegenerator.py	84.00%	4 Missing ⚠️
tests/test_fieldset_sampling.py	90.90%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1641      +/-   ##
==========================================
- Coverage   81.18%   80.93%   -0.26%     
==========================================
  Files          72       74       +2     
  Lines       13256    13435     +179     
  Branches      127      128       +1     
==========================================
+ Hits        10762    10873     +111     
- Misses       2457     2524      +67     
- Partials       37       38       +1     

Flag	Coverage Δ
integration-tests	64.38% <32.38%> (-0.45%)	⬇️
mypy	15.59% <12.50%> (-0.06%)	⬇️
unit-tests	81.07% <79.11%> (-0.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
parcels/fieldfilebuffer.py	70.16% <100.00%> (+0.47%)	⬆️
parcels/kernel.py	76.30% <100.00%> (+0.13%)	⬆️
parcels/tools/exampledata_utils.py	100.00% <100.00%> (ø)
tests/test_advection.py	97.12% <100.00%> (+0.21%)	⬆️
tests/test_data/fieldset_CROCO2D.py	100.00% <100.00%> (ø)
tests/test_data/fieldset_CROCO3D.py	100.00% <100.00%> (ø)
tests/test_fieldset_sampling.py	93.48% <90.90%> (-0.06%)	⬇️
parcels/compilation/codegenerator.py	78.44% <84.00%> (-0.14%)	⬇️
parcels/field.py	74.74% <79.41%> (-0.09%)	⬇️
parcels/fieldset.py	81.07% <41.46%> (-2.34%)	⬇️
... and 1 more