Brownian motion example documentation

[cmaclell]

Hello, I'm trying to understand how the brownian motion kernel works.

To get an example working I've been building off of the brownian motion example here: https://github.com/OceanParcels/parcels/blob/master/parcels/examples/example_brownian.py

Two questions:

• Why are the Kh_zonal and Kh_meridional 2x2 matrices of with the diffusion constants (for U and V)? Is this somehow representing the covariance between the U and V values?
• What is the units for the kh_zonal = 100 and kh_meridional = 100 diffusion constants? The example makes it look like this is in degrees, but wouldn't that be an enormous amount of diffusion?

Thanks!

[cmaclell]

I think I see the answer to my first question, the 2x2 matrix is because the zeros_fieldset has dimensions 2x2, so this is just setting the Kh_zonal and Kh_meridional values for every location in the grid.

Also, it looks like the zeros_fieldset has mesh type flat, does this mean the units are in meters, thus making the kh_zonal and kh_meridional diffusion constants in m/s?

[cmaclell]

So digging thorough the test code here: https://github.com/OceanParcels/parcels/blob/b862cabfd28a3361ad57ab97464e623cb10423bb/tests/test_diffusion.py

It looks like there is some kind of conversion going on (see line 27): mesh_conversion = 1/1852./60 if mesh is 'spherical' else 1

This seems to imply that it is necessary to convert the mesh type so that the units are handled correctly.

Also, I found something in the unit converter class that looks like it is doing some kind of automatic conversion for Kh_zonal and Kh_meridional values:

unitconverters_map = {'U': GeographicPolar(), 'V': Geographic(),
                      'Kh_zonal': GeographicPolarSquare(),
                      'Kh_meridional': GeographicSquare()}

Now I'm really confused about what units those constants are in.

[erikvansebille]

Thanks, @cmaclell for this question. Indeed, the way that we treat units in Parcels was far from clear, and poorly documented. I've now added a tutorial which I hope explains better what goes on under the hood.

Let us know if things are still unclear!

[cmaclell]

Thank you very much for your example tutorial on unit conversions, this makes things much clearer!