Improve interface of forward models in Harmonica?

[santisoler]

TL;DR (too long, didn't read)

I opened a poll to make a community-based decision on the design of the forward modelling functions in Harmonica.

The idea is to avoid passing the desired fields as strings (like we currently do):

hm.prism_gravity(coordinates, prisms, density, field="potential")
hm.prism_gravity(coordinates, prisms, density, field="g_z")

but create separate functions for each available field, like:

hm.prism_gravity_potential(coordinates, prisms, density)
hm.prism_gravity_z(coordinates, prisms, density)

Complete the poll and optionally add a comment if you have any good ideas! We want to hear them!

The problem

Hi everyone! All across the Fatiando project we have to make design decisions every time we implement a new feature. These design decisions can be divided in two big categories:

• the design of underlying code,
• the design of the user interface.

The first one is related to the computational power house, how the computations are efficiently carried out and how their implementations are testable, extendable and maintainable. Since users aren't expected to directly interact with these pieces of code, we have a high flexibility for changes: while ensuring that the public functions and classes recreate the previous results, we can safely refactor the underlying code for speed gain, extensibility and maintainability.

The second set of decisions are harder to make. When we write public functions and classes we expect users to interact with them, so there are a few things that we have to consider while doing so: how easy it is to use it, how clear is the documentation, what's the scope of this function or class, etc. But also we have to consider that users will get used to using these interfaces, so pushing changes to them cannot be arbitrarily done.

In Harmonica we have implemented forward modelling functions since almost we started moving the old Fatiando code into it. In this new design every forward modelling function in available directly from harmonica, instead of having them living inside submodules like in the old fatiando. For example, if we want to compute the downward gravity acceleration of rectangular prisms we can run the following:

import harmonica as hm

hm.prism_gravity(coordinates, prisms, density, field="g_z")

In this design we have a single function to compute any gravity field generated by prisms: the field that the user wants to compute must be passed as a string to the field. This reduces the amounts of functions and condenses every possible gravity field into a single function call. But this comes with a cost: we need to pass the desired field as a string. This imposes some challenges:

• We don't have autocompletion for that field in Jupyter notebooks or IDEs.
• A minor typo can create an error down the road that it's hard to detect until you run it (if we pass "gz" instead of "g_z" we will notice it after running the code unless we visually and carefully inspect it.
• Listing the available fields is done only in the docstring of the prism_gravity function, so you have to read it every time you want to remember exactly which string should you pass so you don't find yourself in the situation described in the previous item.

Possible solution

Considering these drawbacks I thought this might be a good opportunity to change that design decision. Instead of passing the field as a string I think we could create separate forward modelling functions for each component. For example, for the downward component of the acceleration of the prism it could be something like:

import harmonica as hm

hm.prism_gravity_downward(coordinates, prisms, density)

While the gravitational potential and the two other components of the acceleration could be functions named:

hm.prism_gravity_potential(coordinates, prisms, density)
hm.prism_gravity_easting(coordinates, prisms, density)
hm.prism_gravity_northing(coordinates, prisms, density)

We could also use this design for tensor components:

hm.prism_gravity_ee(coordinates, prisms, density)
hm.prism_gravity_nn(coordinates, prisms, density)
hm.prism_gravity_zz(coordinates, prisms, density)
hm.prism_gravity_en(coordinates, prisms, density)
hm.prism_gravity_ez(coordinates, prisms, density)
hm.prism_gravity_nz(coordinates, prisms, density)

And also for the magnetic fields of prisms (see https://github.com/fatiando/harmonica#366 for a draft implementation of these):

b_easting, b_northing, b_upward = hm.prism_magnetic_field(coordinates, prisms, magnetizations)
b_easting = hm.prism_magnetic_easting(coordinates, prisms, magnetizations)
b_northing = hm.prism_magnetic_northing(coordinates, prisms, magnetizations)
b_upward = hm.prism_magnetic_upward(coordinates, prisms, magnetizations)

Since this decision would impact most Harmonica users I thought this might be a good opportunity to include them in this design decision. I left a poll for you to put your thoughts on it, but I would like to encourage you to comment on this discussion and give more detailed thoughts.

[mjfield2]

I like the current simplicity of the API. Creating functions for each component seems like it would bloat the API and documentation. I see how passing string parameters may be non-ideal, but at least it is simple to look at a single forward modeling function in the documentation.

[santisoler]

Thanks @mjfield2 for your input! I'm glad you enjoy the current API.

[LL-Geo]

I like the current design, haha.

[santisoler]

Thanks @LL-Geo for the vote! Glad to know the current design is not as bad as I thought.

[mdtanker]

Yes I agree with the above and think the simplicity of the current docs is more important than having auto-completion.