Contributing to HTM#

Contribution workflow#

  1. Fork the repository

First, create a fork of the repository. This is a personnal copy of the repository where you can commit changes without interfering with other developers.

htm_repo_screenshot

  1. Clone your fork and create a development branch:

    git clone https://github.com/your_username/h-transport-materials
cd h-transport-materials
git checkout -b newbranch

  2. Make your changes. Make sure you tested your code.

  3. Push and open a pull request. Automatically, the test suite will be run.

  4. One of the maintainers will review the pull request. Any potential issues with the pull request can be discussed directly here. If need be, simply commit new changes to your development branch to update the pull request.

Add a property#

If you want to add a property of a material that doesn’t already exist in the database, first add the material.

Rules for adding a property#

  • The property doesn’t already exist in the HTM database

  • The property comes from a published source

  • The property must have the following attributes:

    • Arrhenius parameters or experimental datapoints

    • a source

    • an isotope

    • a range (if it doesn’t have experimental datapoints)

    • a material

Best practices#

  • Use the units given by the author, minimise manual conversions. See Units for more information on units in HTM.

  • Whenever possible use the experimental data provided by the authors. If for some reason it isn’t possible, leave a note and/or a # TODO comment.

  • Add anything relevant to the property with the note argument.

  • If there is a discrepency in the original paper (for example: the equation and the plotted curve don’t match):

    1. Use the datapoints

    2. Indicate the discrepency in note

Experimental data#

When providing experimental data, no need to add a range value: the temperature range will be worked out from the experimental points directly.

In papers, experimental datapoints are either:

Given in a table in the paper#

If the dataset is small, the data can be either copied to the python script. Otherwise, the data can be stored in a CSV file and then read by the python script. See below how to add a CSV file in HTM.

It is recommended to add a reference to where the data is in the paper in note (eg. "table 7"). This way, it is easy for users to find the origin of the data without having to read the whole paper:

my_diff = Diffusivity(
    data_T=np.array([200, 300, 400, 500]) * htm.ureg.K,
    data_y=[1, 2, 3, 4] * htm.ureg.cm**2 * htm.ureg.s**-1,
    source="the_reference",
    note="data can be found in Table 7"
)

From a graph#

If the data is only plotted on a graph, numerise the plots with WebPlotDigitizer and export it as a CSV file. As transparency and reproductibility are at the heart of the HTM philosophy, please attach the WebPlotDigitizer project to HTM:

  1. Download the project as a .tar archive File/SaveProject.

  2. Move the .tar file to the appropriate folder inside property_database/

  3. If several subfolders were added, add a __init__.py file to all the subfolders to make them importable

The folder should look like:

h_transport_materials/h_transport_materials
| property_database
| |  ...
| | name_of_material
| | | __init__.py
| | | name_of_material.py
| | | author_year.tar
| | | property_data.csv

In the case where several WebPlotDigitizer projects are present:

h_transport_materials/h_transport_materials
| property_database
| |  ...
| | name_of_material
| | | __init__.py
| | | name_of_material.py
| | | author_year
| | | | __init__.py
| | | | property1.tar
| | | | property2.tar
| | | | property1_data.csv
| | | | property2_data.csv

Depending on how the .csv file is formatted, the python code should look like:

data = np.genfromtxt(
    str(Path(__file__).parent) + "/oishi_1989_diffusivity.csv",
    delimiter=",",
    names=True,
)

my_diff = Diffusivity(
    data_T=(1 / data["X"]) * htm.ureg.K,
    data_y=data["Y"] * htm.ureg.cm**2 * htm.ureg.s**-1,
    source="the_reference",
)

Given as a supplementary file#

If the authors provide data as a supplementary file (rather uncommon), either download the file and put a copy in the appropriate folder then read directly from this file. It is recommended to add a link to the data supplementary file for reproductibility sake.

Reference#

When adding a property, the reference should be given as a bibtex reference. The reference should be citable and a DOI is preferred. See Add a reference to see how to add a reference.

Material#

All the properties in the database must have a corresponding material. See Attach a material to learn how to add a material to a property. If the property material doesn’t exist, refer to Adding a new material.

Adding a new material#

To add a material, go to h_transport_materials/material.py and create a new Material() object. Use the class appropriate to the material. For instance, when adding an alloy:

import h_transport_materials as htm

MY_ALLOY = htm.Alloy("name_of_my_alloy")

When adding a pure metal:

MY_METAL = htm.PureMetal("name", "symbol")

By convention, the name of the variable for the Material() should be capitalized.

Then, create a file in h_transport_materials/property_database with the name of the material (eg. tungsten.py). If need be, put this script in a folder with the name of the material (see From a graph).

The new material can then be added to the properties (see Attach a material).

Adding a feature#

Before starting working on a new feature, reach out to the users and developers of HTM by raising an issue. Here we’ll be able to discuss the implementation of this feature and maybe even improve the idea.

Then, follow the usual Contribution workflow and be sure to add a test that proves your feature works. More info on python testing here.

Fixing a bug#

Before starting making changes to fix a bug, please open an issue reporting the bug (if there isn’t one already). To be as efficient as possible, the issue should contain a Minimal Working Example that reproduces the bug.

When fixing a bug, follow the usual Contribution workflow but add a test that catches the bug to prove that your fix is effective. More info on python testing here.

Testing your code#

Regardless the addition (contributing to the database, fixing a bug, adding a feature…), your code needs to be tested. When you open a pull request, your code will automatically be tested by running the test suite. The test suite can be found in the tests folder.

To test the local source code, run:

pytest .

You may have to install the tests dependencies (like pytest):

pip install -e .[tests]