How to Add New Code¶
This document details the process of adding new code into freud.
Does my code belong in freud?¶
The freud library is not meant to simply wrap or augment external Python libraries. A good rule of thumb is if the code I plan to write does not require C++, it does not belong in freud. There are, of course, exceptions.
Create a new branch¶
You should branch your code from master
into a new branch. Do not add
new code directly into the master
branch.
Add a New Module¶
If the code you are adding is in a new module, not an existing module, you must do the following:
Create
cpp/moduleName
folderEdit
freud/__init__.py
Add
from . import moduleName
so that your module is imported by default.
Edit
freud/_freud.pyx
Add
include "moduleName.pxi"
. This must be done to have freud include your Python-level code.
Create
freud/moduleName.pxi
fileThis will house the python-level code.
If you have a .pxd file exposing C++ classes, make sure to import that:
cimport freud._moduleName as moduleName
Create
freud/moduleName.py
fileMake sure there is an import for each C++ class in your module:
from ._freud import MyC++Class
Create
freud/_moduleName.pxd
This file will expose the C++ classes in your module to python.
Edit
setup.py
Add
cpp/moduleName
to theincludes
list.If there are any helper cc files that will not have a corresponding Cython class, add those files to the
sources
list inside theextensions
list.
Add line to
doc/source/modules.rst
Make sure your new module is referenced in the documentation.
Create
doc/source/moduleName.rst
Add to an Existing Module¶
To add a new class to an existing module, do the following:
Create
cpp/moduleName/SubModule.h
andcpp/moduleName/SubModule.cc
New classes should be grouped into paired
.h
,.cc
files. There may be a few instances where new classes could be added to an existing.h
,.cc
pairing.
Edit
freud/moduleName.py
fileAdd a line for each C++ class in your module:
from ._freud import MyC++Class
Expose C++ class in
freud/_moduleName.pxd
Create Python interface in
freud/moduleName.pxi
You must include sphinx-style documentation and unit tests.
Add extra documentation to
doc/source/moduleName.rst
Add unit tests to
freud/tests