The best way to contribute to the reflectometry package is to work from a copy of the source tree in the revision control system.
The refl1d project is hosted on github at:
You will need the git source control software for your computer. This can be downloaded from the git page, or you can use an integrated development environment (IDE) such as Eclipse and PyCharm, which may have git built in.
If you want to make one or two tiny changes, it is easiest to clone the project, make the changes, document and test, then send a patch.
Clone the project as follows:
git clone https://github.com/reflectometry/refl1d.git
You will need bumps and periodictable to run. If you are fixing bugs in the scattering length density calculator or the fitting engine, you will want to clone the repositories as sister directories to the refl1d source tree:
git clone https://github.com/bumps/bumps.git git clone https://github.com/pkienzle/periodictable.git
If you are only working with the refl1d modeling code, then you can install bumps and periodictable using pip:
pip install periodictable bumps
To run the package from the source tree use the following:
cd refl1d python run.py
This will first build the package into the build directory then run it. Any changes you make in the source directory will automatically be used in the new version.
As you make changes to the package, you can see what you have done using git:
git status git diff
Please update the documentation and add tests for your changes. We use doctests on all of our examples that we know our documentation is correct. More thorough tests are found in test directory. With the nosetest package, you can run the tests using:
Nose is available on linux form apt-get
When all the tests run, create a patch and send it to email@example.com:
git diff > patch
For a larger set of changes, you should fork refl1d on github, and issue pull requests for each part.
Once you have create the fork, the clone line is slightly different:
git clone https://github.com/YourGithubAccount/refl1d
After you have tested your changes, you will need to push them to your github fork:
git log git commit -a -m "short sentence describing what the change is for" git push
Good commit messages are a bit of an art. Ideally you should be able to read through the commit messages and create a “what’s new” summary without looking at the actual code.
Make sure your fork is up to date before issuing a pull request. You can track updates to the original refl1d package using:
git remote add refl1d https://github.com/reflectometry/refl1d git fetch refl1d git merge refl1d/master git push
When making changes, you need to take care that they work on different versions of python. In particular, RHEL6, Centos6.5, Rocks and ScientificLinux all run python 2.6, most linux/windows/mac users run python 2.7, but some of the more bleeding edge distributions run 3.3/3.4. The anaconda distribution makes it convenient to maintain multiple independent environments Even better is to test against all python versions 2.6, 2.7, 3.3, 3.4:
pythonX.Y tests.py pythonX.Y run.py
When all the tests run, issue a pull request from your github account.
Building the package documentation requires a working Sphinx installation, and latex to build the pdf. As of this writing we are using sphinx 1.2.
The command line to build the docs is as follows:
(cd doc && make clean html pdf)
You can see the result by pointing your browser to:
Note that this only works with a unix-like environment for now since we are using make. On windows, you can run sphinx directly from python:
cd doc python -m sphinx.__init__ -b html -d _build/doctrees . _build/html
ReStructured text format does not have a nice syntax for superscripts and subscripts. Units such as g·cm-3 are entered using macros such as |g/cm^3| to hide the details. The complete list of macros is available in
In addition to macros for units, we also define cdot, angstrom and degrees unicode characters here. The corresponding latex symbols are defined in doc/sphinx/conf.py.
There is a bug in older sphinx versions (e.g., 1.0.7) in which latex tables cannot be created. You can fix this by changing:
You can build the standalone executable using the powershell script:
This creates the distribution archive in the dist directory, including python, the application, the supporting libraries and everything else needed to run the application.
The installer build script is run automatically on github in response to a checkin on the master branch (currently via the appveyor.yml file, but maybe moving to github actions).
Note: OS/X installer is no longer maintained.
To build a Mac OS/X standalone executable you will need the py2app package. This should already be available in your mac python environment.
Build the executable using:
This creates a .dmg file in the dist directory with the Refl1D app inside.