Contributing to VICE¶
VICE is written in a cohesive manner around a core set of objects. That is,
VICE’s implementation shares one library, with considerable overlap between
relevant calculations (e.g. the multizone
object makes use of the
singlezone
object, which makes use of the dataframe
objects, and so
on). The dataframe
being the exception which is implemented in Cython
,
the majority of these objects are implemented in C, declared via
typedef struct
statements in the file vice/src/objects/objects.h
.
VICE’s entire C library can be found in the directory vice/src/
, and the
major components of its python implementation in vice/core/
. This includes
the singlezone
and multizone
objects, the dataframe
and all
derived classes, the output
and multioutput
objects, and single
stellar population routines in the vice/core/ssp/
subdirectory. The
hierarchical file structure of these directories is designed to mirror one
another. Separate from the VICE core
is the yields
module, in which
all nucleosynthetic yield calculations are implemented, independent of the
simulation features.
Note
The primary author (James W. Johnson) reserves the right to make revisions to all contributed code and associated documentation.
Building a New Extension¶
To contribute to VICE, first fork the repository and add any necessary
routines in the fork. These changes should reflect the overall design of the
package: with all C extensions in vice/src/
; deviating from this pattern
will cause a broken import following installation of the modified version of
the code. Unless the modification is to the vice/yields/
module, the
python wrapping of these functions should be in vice/core/
.
All extensions should be given unit tests, making use of the moduletest
and unittest
objects scripted in the files vice/testing/moduletest.py
and vice/testing/unittest.py
. These objects can be created from functions
via decorators
. Place @unittest
before a function returning a string
describing the dot-notation path to the function and the unit test function
itself to obtain a unittest
object. Similarly, place @moduletest
before a function return a string describing the dot-notation path to the
module and a list of unittest
and moduletest
objects to obtain a
moduletest
object. Finally, link the tests to that of the parent
directory’s moduletest
object.
Documenting Changes¶
All docstrings visible to the user after installation should be in the
numpydocs
format. This is not required (though recommended) for docstrings
not accessible to the user. Any C routines added to the source code should be
given comment headers with descriptions of their purpose, any parameters they
accept, what they return, and the header files they’re declared in. These
comment headers should reflect the style of those already present in the C
library. Finally, add the new features to the API reference config file at
docs/src/users_guide/pkgcontents/gen/config.py
and generate the
documentation by running make
in the docs/
directory.
Submitting a Contribution¶
To submit your contribution, first conduct the steps outlined above, then please open a pull request, and label it as an enhancement.