Should we explain `fill_halo_regions!()` in the docs?

[tomchor]

fill_halo_regions!() seems to be a very important function in Oceananigans. I've never needed to use it in any script, but based off of some discussions/issues/PRs here it seems like there may be a big benefit to explaining what it does and when it should be used to users (I, for example, don't exactly understand when it's needed). However, it isn't really explained in the docs atm.

Should we dedicate a small section in the docs to explaining this?

[glwagner]

I think we should write a Field tutorial that covers this (and everything else...) It's been on my todo list for so many eons.

fill_halo_regions! certainly is important. This function fills the halo regions of a field --- that is, a buffer of cells that surrounds the "interior" (physical part) of the domain. The halo regions are touched when we evaluate gradients or interpolate across boundaries. They are also used for distributed models (there the halo regions need to be communicated between different regions / processes). In general, the halo regions are linked to the interior values of the field --- so every time interior values are updated, halo regions must be updated for the entire state to be consistent. In short, we need to fill halo regions so that 1) spurious fluxes are not added while evaluating flux divergences across Bounded boundaries for FluxBoundaryConditions; 2) periodicity is correctly enforced in Periodic directions, 3) fluxes are correct for Value/Gradient boundary conditions.

I think our philosophy is generally that we want an API in which users don't need to call this function. It's just that people want to do crazy creative and cool!! things and writing an API that supports it all is hard. Or maybe more importantly its a chicken-egg problem so we (developers) need to see the applications in action first, then we can design an API (at least for those wild applications out there).

That docs section would blur the boundaries between "developer documentation" and ordinary documentation (we also need developer documentation...)

[tomchor]

I think we should write a Field tutorial that covers this (and everything else...) It's been on my todo list for so many eons.

If you start a PR I can help populate it over time (I'm guessing other people would probably wanna contribute too).

fill_halo_regions! certainly is important. This function fills the halo regions of a field --- that is, a buffer of cells that surrounds the "interior" (physical part) of the domain. The halo regions are touched when we evaluate gradients or interpolate across boundaries. They are also used for distributed models (there the halo regions need to be communicated between different regions / processes). In general, the halo regions are linked to the interior values of the field --- so every time interior values are updated, halo regions must be updated for the entire state to be consistent. In short, we need to fill halo regions so that 1) spurious fluxes are not added while evaluating flux divergences across Bounded boundaries for FluxBoundaryConditions; 2) periodicity is correctly enforced in Periodic directions, 3) fluxes are correct for Value/Gradient boundary conditions.

I think our philosophy is generally that we want an API in which users don't need to call this function. It's just that people want to do ~crazy~ creative and cool!! things and writing an API that supports it all is hard. Or maybe more importantly its a chicken-egg problem so we (developers) need to see the applications in action first, then we can design an API (at least for those wild applications out there).

That docs section would blur the boundaries between "developer documentation" and ordinary documentation (we also need developer documentation...)

We could put that in a section called "Information for advanced users" or something like that.

[glwagner]

We could put that in a section called "Information for advanced users" or something like that.

I'd advocate for putting it in the Field tutorial, what do you think? I think users benefit less from "misc info" sections of the docs.

[glwagner]

If you start a PR I can help populate it over time (I'm guessing other people would probably wanna contribute too).

I can work on this. I'm trying to finish immersed boundary fluxes API now though.

[tomchor]

I'd advocate for putting it in the Field tutorial, what do you think? I think users benefit less from "misc info" sections of the docs.

That's good too. I just made that comment in response to your comment quote below:

That docs section would blur the boundaries between "developer documentation" and ordinary documentation (we also need developer documentation...)

[navidcy]

https://github.com/CliMA/Oceananigans.jl/pull/2477 is sort of relevant here

[glwagner]

For sure, because it will fundamentally change the role that fill_halo_regions! plays.