Contributing to SurfaceTopography

Development

To use the code without installing it, e.g. for development purposes, use the env.sh script to set the environment:

source /path/to/SurfaceTopography/env.sh [python3]

Note that the parameter to env.sh specifies the Python interpreter for which the environment is set up. PyCo contains portions that need to be compiled, make sure to run

python setup.py build

whenever any of the pure C (in the c subdirectory) sources are modified.

Code style

Always follow PEP-8. Documentation strings must follow the numpydoc standard.

All parameters (for functions or methods) should be descriptive. Do not name a parameter after a symbol (e.g. lambda) but rather say that it is (e.g. large_wavelength_cutoff).

Development branches

New features should be developed always in its own branch. When creating your own branch, please suffix that branch by the year of creation on a description of what is contains. For example, if you are working on an implementation for hyperdimensional scans and you started that work in 2048, the branch could be called “48_hyperdimensional_scans”.

Commits

Prepend your commits and merge requests with a shortcut indicating the type of changes they contain:

  • API: changes to the user exposed API

  • BUG: Bug fix

  • BUILD: Changes to the build system

  • CI: Changes to the CI configuration

  • DOC: Changes to documentation strings or documentation in general (not only typos)

  • ENH: Enhancement (e.g. a new feature)

  • MAINT: Maintenance (e.g. fixing a typo, or changing code without affecting function)

  • TST: Changes to the unit test environment

  • WIP: Work in progress

The changelog will be based on the content of the commits with tag BUG, API and ENH.

Examples:

  • If your are working on a new feature, use ENH on the commit making the feature ready. Before use the WIP tag.

  • use TST when your changes only deal with the testing environment. If you fix a bug and implement the test for it, use BUG.

  • minor changes that doesn’t change the codes behaviour (for example rewrite file in a cleaner or slightly efficienter way) belong to the tag MAINT

  • if you change documentation files without changing the code, use DOC; if you also change code in the same commit, use another shortcut

Authors

Add yourself to the AUTHORS file using the email address that you are using for your commits. We use this information to automatically generate copyright statements for all files from the commit log.

Writing tests

Older tests are written using the unittest syntax. We now use pytest (that understands almost all unittest syntaxes), because it is compatible with the parallel test runner runtests.

If a whole test file should only be run in serial and/or is incompatible with runtests (unittest), include following line:

pytestmark = pytest.mark.skipif(MPI.COMM_WORLD.Get_size()> 1,
        reason="tests only serial funcionalities, please execute with pytest")

The file will executed in a run with pytest and not with a (parallel) run with python3 run-tests.py

MPI Tests

In order to vary the number of processors used in the tests, you should always explictely use the communicator defined as fixture in tests/conftest.py instead of MPI.COMM_WORLD.

def test_parallel(comm):
    substrate = PeriodicFFTElasticHalfSpace(...., commincator=comm)
    # Take care not to let your functions use their default value
    # for the communicator !

Note: a single test function that should be run only with one processor:

def test_parallel(comm_serial):
    pass

Debug plots in the tests

Often when you develop your test you need to plot and print things to see what happens. It is a good idea to let the plots ready for use:

if False:
    import matplotlib.pyplot as plt
    fig, ax = plt.subplots()
    plt.colorbar(ax.pcolormesh(- system.substrate.force), label="pressure")
    plt.show(block=True)

Compiling the documentation

  • After changes to the SurfaceTopography source, you have to build again: python setup.py build

  • Navigate into the docs folder: cd docs/

  • Automatically generate reStructuredText files from the source: sphinx-apidoc -o source/ ../SurfaceTopography. Do this just once, or if you have added/removed classes or methods. In case of the latter, be sure to remove the previous source before: rm -rf source/

  • Build html files: make html

  • The resulting html files can be found in the SurfaceTopography/docs/_build/html/ folder. Root is SurfaceTopography/docs/_build/html/index.html.