BackgroundField func definition with a flat dimension

[wenegrat]

Hi all,

I'm attempting to run a simulation setup where I'd like to switch between 2D and 3D runs. I have a background field, included with a function definition that has the signature,func(x,y,z,t,p) , this works fine when the model is run in 3D.

However, when I run in 2D (flat x dimension) I get a 'dynamic function invocation' error. I can get rid of the error by instead defining the function signature as func(y,z,t,p).

I see in the documentation it says the function should have all 3 spatial dimensions (https://clima.github.io/OceananigansDocumentation/stable/appendix/library/#Oceananigans.Fields.BackgroundField-Tuple{Any}), however in some of the examples (https://clima.github.io/OceananigansDocumentation/stable/literated/internal_wave/) the flat dimension is dropped from the function definition.

My question is first, is it expected that it will error if I use the `func(x,y,z,t,p)' function definition in a 2D domain? I'm also curious if this has potentially changed at some point (in the last year), as I'm picking up old code that I used to be able to switch between 2D and 3D without change to the function definitions here.

Thanks very much!

[tomchor]

In current versions of the code Flat dimensions must be dropped from the function signature. I think that docstring you linked is out of date, but maybe someone else can confirm.

In order to define your function in a way that works for both 2D and 3D set-ups, you can define both methods. Something like:

func(y,z,t,p) = BLA
func(x,y,z,p) = func(y,z,t,p)

That way if you run your simulation in 2D, Oceananigans will try to use a signature that matches the first method, and the second method for 3D cases. You could also put your define in an if/else statement and only define the method you wanna use, but my opinion is that it's cleaner to avoid the if/else statement.

So to answer your specific questions:

My question is first, is it expected that it will error if I use the `func(x,y,z,t,p)' function definition in a 2D domain?

Yes.

I'm also curious if this has potentially changed at some point (in the last year), as I'm picking up old code that I used to be able to switch between 2D and 3D without change to the function definitions here.

Yes, this changed a few months ago. I think it was a PR by @glwagner but I can't find it right now.

[wenegrat]

Thank you!

[glwagner]

Hmm, if there are docs to fix would be good to do that!

On the function signature thing... it does seem like there are some pretty big trade-offs to that change so it could be good thinking hard about... we didn't just change background field but also forcing, boundary conditions, set!, bathymetry.

The main benefit is readability, ie if you show your script to someone, or present it to a class for teaching (for example), it makes more sense that f(x, y) applies to a 2D simulation in x, y, a function f(z) applies to a 1D simulation in z, etc. For the shallow water model, for example, it's nice that functions don't have to depend on a spurious "z" which doesn't actually exist.

But there's a downside that its not quite as effortless to migrate functionality from 1D to 2D to 3D.

One fix could be to introduce a way to declare that a function depends on y, z, t rather than x, y, z, t, for example, and then it would work in both 2D and 3D.