It would be great to clarify this in the Project Goals. For example, I noticed that the functions don't include universal constants or physical properties. For gravity, this is ok since getting the gravity field is a matter of simple multiplication. For magnetics, the combination is a bit more difficult since it involves a dot product with the vector magnetisation. So it would be worth having that in a function already instead of requiring users to code it. It also may be necessary since doing it out of the jit compiled function would mean losing parallel and low memory execution.

It would be worth clarifying the scope of the package with this in mind. A good way to go about it would be to try to add a magnetic dipole implementation to see how it fits with the current paradigm.

Or maybe the "kernel" could mean the version without the for loops? It may be worth making that available in the API for use in external jit-compiled code (like tesseroids).

It would be helpful to have an early release of Choclo (even as it is now) for a few reasons:

• Guarantee the name on PyPI
• Start building a conda-forge package
• Start using the magnetic models in Harmonica
• Make sure our CI and deployment are working

The only roadblock I see for doing this right now is the lack of the PyPI Actions workflow.

@santisoler what do you think?

Description of the desired feature:
The library already contains the function dipole.magnetic_field() to calculate the magnetic field of a single dipole, where both the positive and negative poles are at the same point q.

I would very much like to see a function to calculate the same for the case where there's a distance between the positive and negative poles. That is to say, some kind of rod/cylinder/wire, described as two end-points q1=(x1, y1, z1) and q2=(x2, y2, z2).

Otherwise, maybe point me in the right direction, where I can find the equations to implement this myself.

The forward modelling functions for point masses make use of kernel functions for each field. These functions executes just a single line and they are mostly repeated documentation. Besides, we don't expect using those functions outside the forward modelling of point sources in cartesian coordinates, so we could simplify the API by removing those and include their code in the forward modelling functions.

Worth noting that for the spherical coordinates forward modelling functions we want those kernels so they can be used for forward modelling tesseroids (check harmonica.tesseroid_gravity).

Choclo needs installation instructions. Now that it's available through pip and conda-forge, we can easily reuse the installation page we have for the other packages, like Harmonica.

Description of the desired feature:

For larger scale applications, it would be great to have versions of the point mass code in spherical coordinates. The input coordinates would be in longitude, spherical latitude, and radius and the output vector components would be in a local Cartesian system (east, north, up).

The equations for this can be found in this paper: https://doi.org/10.1007/s00190-008-0219-8

The format for the functions would be pretty much the same as those in choclo/point/_forward.py. The new functions implemented in 2 places (not sure which would be best):

1. In a module called choclo/point_spherical/_forward.py and they would have the same name as their cartesian counterparts.
2. In choclo/point/_forward_spherical.py and they would be called gravity_spherical_e, and so on.

I'm leaning towards option 2.

Are you willing to help implement and maintain this feature?

Maybe but it will be a while before I have to do it, so please be my guest!

The magnetic_field function points to magnetic_e, magnetic_n and magnetic_u functions for computing single components of the magnetic field. These functions should be properly linked to so Sphinx can create anchor links to them.

For the early release I'm not going to upload to Zenodo or add a changelog.

Make a release

After the changelog PR is merged:

• Draft a new release on GitHub
• The tag and release name should be a version number (following Semantic Versioning) with a leading v (v1.5.7)
• Fill the release description
• Publish the release

Create Conda-forge package

• TODO

When this issue is solved, we can close #23

Once we reserve a DOI in Zenodo for Choclo we need to add it to CITATION.rst

I've been experimenting with using the choclo kernels for magnetic forward modelling and have run into an issue with the inputs. For dipoles, the magnetic moment is supposed to be an array. This works well if my wrapper function already takes the moment vectors for several dipoles as a 2D array with 1 vector per row. Then I can pass moment[j, :] to choclo. But if my magnetic moments are in any other format (for example, a tuple with 1 array per component), then I'd need to reshape and possibly reallocate memory just to get things in the proper format for choclo.

Instead, I'm thinking that choclo functions should always take scalar inputs. So the magnetization/dipole moment should be 3 arguments, 1 per component. For prisms, the prism itself is passed as an array and has the same issue. So maybe it should also be 6 arguments instead of 1. This way, the library using choclo in the backend can choose whatever input type they want and doesn't have to reshape just to use choclo.

I'd be willing to make the changes required to the inputs. I actually already started with the dipole moment before realising that the prism geometry had the same issue.

Description of the desired feature:

After #51 is done and we have the gravity gradient components in spherical coordinates, the magnetic fields of dipoles in spherical coordinates would be very straight forward because the kernel functions are the same as the gravity gradients (see the code for the prism magnetic field). So this shouldn't be too much work to implement.

Are you willing to help implement and maintain this feature?

Maybe but it will be a long time before I can find the time to do this. So if anyone wants to have a go, please feel free to do so!

Page that contains the error or needs to be improved (paste link):

https://www.fatiando.org/choclo/latest/index.html

Description of the problem/suggestion:

The Choclo overview could be improved:

• Plot results instead of printing huge arrays
• Don't ravel the coordinates, redesign the example forward functions to handle broadcasting and raveling.
• Fix rst format: some portions need to use the double tick to make them look like code rather than italics.

Zenodo DOI: 10.5281/zenodo.7931023

Target date: 2023/05/12

Draft a Zenodo archive (to be done by a manager on Zenodo)

• Go to the Zenodo entry for this project (find the link to the latest Zenodo release on the README.md file)
• Create a "New version" of it.
• Delete all existing files
• Copy the reserved DOI to this issue
• Update release date
• Update version number (make sure there is a leading v, like v1.5.7)
• Add as authors any new contributors who have added themselves to AUTHORS.md in the same order
• Ensure that the first author is "Fatiando a Terra Project" and others are listed alphabetically by last name
• Save the release draft

Update the changelog

• Generate a list of commits between the last release tag and now: git log HEAD...v1.2.3 > changes.rst
• Edit the list to remove any trivial changes (updates by the bot, CI updates, etc).
• Organize the list into categories (breaking changes, deprecations, bug fixes, new features, maintenance, documentation).
• Add a list of people who contributed to the release: git shortlog HEAD...v1.2.3 -sne
• Add the release date and Zenodo DOI badge to the top
• Replace the PR numbers with links: sed --in-place "s,#\([0-9]\+\),\`#\1 <https://github.com/fatiando/PROJECT/pull/\1>\`__,g" changes.rst
• Check that you changed the PROJECT placeholder when running the last command.
• Copy the changes to doc/changes.rst
• Make a Markdown copy of the changelog: pandoc -s changes.rst -o changes.md --wrap=none
• Add a link to the new release version documentation in README.rst and doc/versions.rst (if the file exists).
• Build and serve the docs locally with make -C doc all serve to check if the changelog looks well
• Open a PR to update the changelog
• Merge the PR

Make a release

After the changelog PR is merged:

• Draft a new release on GitHub
• The tag and release name should be a version number (following Semantic Versioning) with a leading v (v1.5.7)
• Fill the release description with a Markdown version of the latest changelog entry (including the DOI badge)
• Publish the release

Publish to Zenodo

• Upload the zip archive from the GitHub release to Zenodo
• Double check all information (date, authors, version)
• Publish the new version on Zenodo

Conda-forge package

A PR should be opened automatically on the project feedstock repository.

• Add/remove/update any dependencies that have changed in meta.yaml
• If dropping/adding support for Python/numpy versions, make sure the correct version restrictions are applied in meta.yaml
• Merge the PR

Zenodo DOI: 10.5281/zenodo.10951580

Target date: 2024/04/09

Draft a Zenodo archive (to be done by a manager on Zenodo)

• Go to the Zenodo entry for this project (find the link to the latest Zenodo release on the README.md file)
• Create a "New version" of it.
• Delete all existing files
• Copy the reserved DOI to this issue
• Update release date
• Update version number (make sure there is a leading v, like v1.5.7)
• Update version number in Title (use a leading v as well)
• Add as authors any new contributors who have added themselves to AUTHORS.md in the same order
• Ensure that the first author is "Fatiando a Terra Project" and others are listed alphabetically by last name
• Save the release draft

Update the changelog

• Generate a list of commits between the last release tag and now: git log HEAD...v1.2.3 > changes.rst
• Edit the list to remove any trivial changes (updates by the bot, CI updates, etc).
• Organize the list into categories (breaking changes, deprecations, bug fixes, new features, maintenance, documentation).
• Add a list of people who contributed to the release:

  export last_release="v1.2.3"
  git shortlog HEAD...$last_release -sne > contributors
  git log HEAD...$last_release | grep "Co-authored-by" | sed 's/Co-authored-by://' | sed 's/^[[:space:]]*/ /' | sort | uniq -c | sort -nr | sed 's/^ //' >> contributors
  sort -rn contributors

• Add the release date and Zenodo DOI badge to the top
• Replace the PR numbers with links: sed --in-place "s,#\([0-9]\+\),\`#\1 <https://github.com/fatiando/PROJECT/pull/\1>\`__,g" changes.rst
• Check that you changed the PROJECT placeholder when running the last command.
• Copy the changes to doc/changes.rst
• Make a Markdown copy of the changelog: pandoc -s changes.rst -o changes.md --wrap=none
• Add a link to the new release version documentation in README.rst and doc/versions.rst (if the file exists).
• Build and serve the docs locally with make -C doc all serve to check if the changelog looks well
• Open a PR to update the changelog
• Merge the PR

Make a release

After the changelog PR is merged:

• Draft a new release on GitHub
• The tag and release name should be a version number (following Semantic Versioning) with a leading v (v1.5.7)
• Fill the release description with a Markdown version of the latest changelog entry (including the DOI badge)
• Publish the release

Publish to Zenodo

• Upload the zip archive from the GitHub release to Zenodo
• Double check all information (date, authors, version)
• Publish the new version on Zenodo

Conda-forge package

A PR should be opened automatically on the project feedstock repository.

• Add/remove/update any dependencies that have changed in meta.yaml
• If dropping/adding support for Python/numpy versions, make sure the correct version restrictions are applied in meta.yaml
• Merge the PR

Description of the desired feature:

Inline with #30, the magnetic forward modelling functions for prism should return nan on the same singular points of the gravity tensor components, but also for any point inside the prism, since the magnetic field we compute is obtained after assuming we are outside of sources.

Are you willing to help implement and maintain this feature?

Sure!