fatiando / choclo

Kernel functions for your geophysical models

Kernel functions for your geophysical models

Documentation (latest) • Documentation (main branch) • Contributing • Contact

Part of the Fatiando a Terra project, built in collaboration with SimPEG

About

Choclo is a Python library that hosts optimized kernel functions for running geophysical forward and inverse models, intended to be used by other libraries as the underlying layer of their computation. "Choclo" is a term used in some countries of South America to refer to corn, originated from the quechua word chuqllu.

Project goals

• Provide optimized kernel functions for gravity and magnetic forward and inverse models that can be easily harnessed by different geophysical libraries.
• Generate a pure-Python library that could be easily distributed and installed on any operating system.
• Rely on Numba for just-in-time compilations and optional parallelization.
• Keep the dependencies to the bare minimum to encourage other libraries to depend on Choclo.

Project status

Choclo is ready for use but still changing. This means that we sometimes break backwards compatibility as we try to improve the software based on user experience, new ideas, better design decisions, etc. Please keep that in mind before you update Choclo to a newer version.

We welcome feedback and ideas! This is a great time to bring new ideas on how we can improve the project. Join the conversation or submit issues on GitHub.

Getting involved

🗨️ Contact us: Find out more about how to reach us at fatiando.org/contact.

👩🏾‍💻 Contributing to project development: Please read our Contributing Guide to see how you can help and give feedback.

🧑🏾‍🤝‍🧑🏼 Code of conduct: This project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

Imposter syndrome disclaimer: We want your help. No, really. There may be a little voice inside your head that is telling you that you're not ready, that you aren't skilled enough to contribute. We assure you that the little voice in your head is wrong. Most importantly, there are many valuable ways to contribute besides writing code.

This disclaimer was adapted from the MetPy project.

License

This is free software: you can redistribute it and/or modify it under the terms of the BSD 3-clause License. A copy of this license is provided in LICENSE.txt.

choclo's Issues

Ditch the kernels functions for point masses

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).

Release v0.0.1

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

Add point mass gravity fields in spherical coordinates

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!

Early release of Choclo

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?

Fix links to other functions in `dipole.magnetic_field` function

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.

Add Choclo DOI in CITATION.rst

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

Return nan when computing magnetic field inside a prism

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!

Add dipole magnetic fields in spherical coordinates

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!

Should any inputs be arrays/lists?

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.

Add installation instructions to the docs

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.

Clarify what is meant by "kernel"

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).

Release v0.1.0

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

Release v0.2.0

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

Magnetic field between two poles

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.

Improve overview of Choclo

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.