Consider alternative naming convention for grid-dependent kernel functions

[bgroenks96]

@glwagner suggested a naming convention for kernel functions of the form foo(i, j, k, grid, ...):

a convention we are introducing in Breeze to handle the name mangling between "gridded" functions and "pointwise" objects is something like this:

soil_volume = grid_soil_volume(i, j, k, grid, args...)

eg prefix the "i, j, k, grid" versions with grid_

My feeling is that this is kind of redundant since i, j, k, grid already communicates this, but happy to hear others' thoughts.

[glwagner]

the issue is tha tyou can't write

soil_volume = soil_volume(i, j, k, grid, args...)

but another solution is to introduce mathematical notation, eg

V = soil_volume(i, j, k, grid, args...)

[bgroenks96]

If the main issue is just name shadowing, you can also just use a different variable name?

vol = soil_volume(i, j, k, grid, args...)

which is what I typically do at the moment. Or do you not like that because vol is too vague?

[glwagner]

I would personally discourage two things: 1) introducing synonyms or homonyms, which can make code harder to understand or remember and 2) using names that are a "mixture" between mathematical notation and English words.

There is no meaningful difference, outside of context, between "vol" and "soil_volume". We could just as easily have written

soil_volume = vol(i, j, k, grid, args...)

Using fragments like "vol" is very common in scientific code, but I argue its bad practice. It tries to serve two goals --- sufficiently verbose to be understood, but more compact so it "looks like math", but arguably in many cases, does not actually achieve either goal. I think a better solution is to be disciplined about either using English names OR mathematical notation, without gray area between. Rules are meant to be broken, of course, but it could be a good idea to start with this rule. The mathematical notation then must be documented.

We are trying to be careful about this in Breeze: https://numericalearth.github.io/BreezeDocumentation/dev/appendix/notation/

(the notation.md is also a reference for agentic coding tools)

Just my thought. You can disagree.

[bgroenks96]

I see your point, I don't think I disagree, but I think this is a hard habit to break.

Are you also opposed to adding verbs to clarify that a function is actually doing something? e.g.

soil_volume = compute_soil_volume(i, j, k, grid, args...)

[glwagner]

I think that is good style to use verbs!