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#

Navigate to the GitHub repository (cofi, or cofi-examples if you’d like to add or edit things in the example gallery)
Click the “Fork” button on top right of the page (followed by a confirmation page with a “Create fork” button)
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

The fork now stays remotely on GitHub servers, what’s next is to “clone” it into your computer locally:

$ git clone https://github.com/YOUR_GITHUB_ACCOUNT/cofi.git
$ git remote add upstream https://github.com/inlab-geo/cofi.git
$ git fetch upstream

replacing YOUR_GITHUB_ACCOUNT with your own account.

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:

If you are going to work on adding new forward examples, then make sure you have CoFI installed in the usual way.
If you are going to work on adding/linking new inversion tool, or looking to add features or fix bugs in the library core, then try to prepare your environment to have dependencies listed in this environment_dev.yml file. It’s easy to set this up using conda under your local clone:
```
$ conda env create -f envs/environment_dev.yml
$ conda activate cofi_dev
$ pip install -e .
```
If you’d like to edit the documentation, then get the dependencies listed in this requirements.txt file. Set up this with pip:
```
$ pip install -r docs/requirements.txt  # in a virtual environment
$ pip install -e .
```

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:

adding new forward examples
adding/linking new inversion tool
add features or fix bugs
edit the documentation

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_inference_tool.py <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/__init__.py 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.

Checklist

Have you added a new file with a proper name under src/cofi/tools/?
Have you declared the tool class as a subclass of tools.BaseInferenceTool?
Have you implemented __init__ and __call__ methods minimally?
If you’d like us to do input validation, have you defined class variables required_in_problems, optional_in_problem, required_in_options and optional_in_options?
If you’d like us to display the tool related information properly, have you defined class variables short_description and documentation_links?
Have you imported and added the tool subclass name to src/cofi/tools/__init__.py?
Have you added tool name and class reference to the inference_tools_table in file src/cofi/tools/__init__.py?
Have you written tests for your new inference tool under tests/cofi_tools?

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#
Functionality	Code file path
`BaseProblem`	src/cofi/base_problem.py
`InversionOptions`	src/cofi/inversion_options.py
`Inversion`	src/cofi/inversion.py
`InversionResult`	src/cofi/inversion.py
inference tools tree	src/cofi/tools/__init__.py
inference tool dispatch function	src/cofi/inversion.py
`BaseInferenceTool`	src/cofi/tools/base_inference_tool.py
validation for `BaseProblem` and `InversionOptions` objects	src/cofi/tools/base_inference_tool.py

Checklist on adding a new set method in BaseProblem

Except for tests, all changes should take place in src/cofi/base_problem.py.

add method set_something(self, something)
add property/method something(self)
add method something_defined(self) -> bool
add something to list BaseProblem.all_components
write tests in tests/test_base_problem.py (“test_non_set”, etc.)

Documentation#

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
Home	docs/index.rst
Installation	docs/installation.rst
Tutorials (front page)	docs/tutorials/scripts/README.rst
Tutorials (tutorials content)	cofi-examples tutorials/tutorial_name.ipynb
Example gallery (front page)	docs/examples/scripts/README.rst
Exmaple gallery (examples content)	cofi-examples examples/example_name/example_name.ipynb
Frequently asked questions	docs/faq.rst
List of functions and classes (API)	docs/api/index.rst
API reference for BaseProblem	src/cofi/base_problem.py
API reference for InversionOptions	src/cofi/inversion_options.py
API reference for Inversion	src/cofi/inversion.py
API refernece for InversionResult	src/cofi/inversion.py
API reference for BaseInferenceTool	src/cofi/tools/base_inference_tool.py
Change Log	CHANGELOG.md
Contribute to CoFI	dos/contribute.rst

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

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.

reStructuredText

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,

Follow instructions here to set up environment if you haven’t done so yet.
Run all the tests with
```
$ pytest tests
```
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.
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.