Contribute to CoFI#

Great to see you here! There are many ways to contribute to CoFI.

Reporting issues#

Bug reports and feature requests are welcome. Please search before lodging an issue at our Github repository.

Code contribution#

Thanks for making cofi better through coding! You don’t have to know all the details in order to contribute. If you feel confused and are unsure where to start, don’t hesitate to contact us via GitHub issues or Slack.

General Workflow#

Here is a general flowchart for code contribution, including preparation, editing and submitting stages:

%%{init: {'theme':'base'}}%% flowchart LR subgraph PREPARATION [ ] direction TB fork(fork repository)-->clone(create local clone) clone-->env_setup(environment setup) end subgraph EDIT [ ] direction TB code(start coding)-->commit(commit as needed) commit-->push(push to your own fork) end subgraph SUBMIT [ ] direction TB pr(create pull request)-->modify(edit based on our comments) modify-->commit_push(commit and push) commit_push-->merge(we merge it once ready) pr-->merge end PREPARATION-->EDIT EDIT-->SUBMIT

Fork and clone respository#

  1. Navigate to the GitHub repository (cofi, or cofi-examples if you’d like to add or edit things in the example gallery)

  2. Click the “Fork” button on top right of the page (followed by a confirmation page with a “Create fork” button)

  3. Now you’ll be redirected to your fork of cofi, which is like a branch out in your namespace. (And later you will see it merges back when your pull request is approved)

    %%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel': false}} }%% gitGraph commit commit branch your_own_fork checkout your_own_fork commit commit checkout main merge your_own_fork commit commit
  4. The fork now stays remotely on GitHub servers, what’s next is to “clone” it into your computer locally:

    $ git clone
    $ git remote add upstream
    $ git fetch upstream

    replacing YOUR_GITHUB_ACCOUNT with your own account.

  5. If you are working on documentation, then remember to update the submodule linked to cofi-examples:

    $ cd cofi
    $ git submodule update --init

Environment setup#

The environment setup is different depending on your purpose:

Coding / editing#

Quick reference for working with the codebase:

To install:

pip install -e .

To test:

coverage run -m pytest

To auto-format:

black . or black --check . to check without changing

Additionally, we have some guidance on the following scenarios:

Again, don’t hesitate to ask us whenever you feel confused. Contact us via GitHub issues or Slack.

Commit, push and pull request#

The git commit operation captures the staged changes of the project.

The git add command is how you add files to the so-called “staging” area.

Therefore, a typical pattern of commiting a change is:

$ git add path1/file1 path2/file2
$ git commit -m "my commit message"

Please note that we aim to use Angular style commit messages throughout our projects. Simply speaking, we categorise our commits by a short prefix (from feat, fix, docs, style, refactor, perf, test and chore).

Once your changes are committed, push the commits into your remote fork:

$ git push

Open the remote repository under your GitHub account, you should be able to see the new commits pushed.

Now that you’ve finished the coding and editing work, look for the “Contribute” button -> “Open pull request”, write a description and continue as prompted.

Once your pull request is submitted, we are able to see it and will work our best to review and provide feedback as soon as we can. Thanks for all the efforts along the way of contributing! 🎉🎉🎉

Coding in CoFI#

New forward example#

CoFI doesn’t have any forward solvers in the package itself. Instead, we manage all of our forward code as a part of the example gallery maintained in the cofi-examples respository.

Follow the instructions here for details on how to contribute to the example repository.

Our tutorials page is a good place to start learning about how to plug in an inversion problem in cofi. Furthermore, there are examples with increasing complexity presented in the example gallery page for you to learn from.

New inversion tool#

Thank you for your attempt in enriching cofi’s library pool.

To get started, run the helper script:

$ python tools/ <new_tool_name>

To define and plug in your own inference tool backend, you minimally have to create a subclass of tools.BaseInferenceTool and implement two methods: __init__ and __call__. Additionally, add the name and class reference to our inference tools tree under src/cofi/tools/ so that our dispatch routine can find the class from the name specified in an InversionOptions instance.

Documentation API reference - BaseInferenceTool provides further details and examples.

Follow the environment setup section to set up the package and commit, push and pull request section to raise a pull request.

We would also appreciate it if you write tests that ensure a good coverage under the file path tests.

Feature or bug fixes in cofi core#

Here we provide a mapping table to the parts of code related to each existing feature.

Table: feature mapping to code file#


Code file path









inference tools tree


inference tool dispatch function




validation for BaseProblem and InversionOptions objects



It’s very easy to edit or write documentation for CoFI. Start by cloning our GitHub repository and setting up the environment, following instructions above - fork & clone and environment setup. Then head straight to the parts that you want to change, based on the mapping table below:

Table: documentation page mapping to file path#

Documentation page

File location





Tutorials (front page)


Tutorials (tutorials content)

cofi-examples tutorials/tutorial_name.ipynb

Example gallery (front page)


Exmaple gallery (examples content)

cofi-examples examples/example_name/example_name.ipynb

Frequently asked questions


List of functions and classes (API)


API reference for BaseProblem


API reference for InversionOptions


API reference for Inversion


API refernece for InversionResult


API reference for BaseInferenceTool


Change Log

Contribute to CoFI


To change the configuration of this documentation, go change the content in file docs/

To adjust the styling of pages, modify things in docs/_static/style.css and docs/_templates.

To test the changes, go to docs directory, run make html and open the file docs/_build/html/index.html in your browser to see the changes.


All of the documentation (except for the ChangeLog part), including API references, use the reStructuredText format. This is a textual file format that tends to be more powerful compared to markdown.

For the purpose of CoFI documentation, a good resource for reStructuredText syntax is the sample project (we link to the Book theme, the one this documentation uses), with the sources here to refer to.

Testing in CoFI#

When you submit a pull request, an automatic testing job will be triggered on GitHub.

If you’d like to test your changes locally,

  1. Follow instructions here to set up environment if you haven’t done so yet.

  2. Run all the tests with

    $ pytest tests
  3. Check the test coverage with

    $ coverage -m pytest tests; coverage report; coverage xml

    If possible, write tests for your new code to ensure a good coverage.

  4. To generate and check documentation locally,

    $ cd docs
    $ make html
    $ python -m http.server -d build/html

    Put localhost:8000 into your browser address bar to read the generated documentation.