Developer Information¶
Environment¶
SME is not pure python. SME calls C++ and fortran dynamic libraries, which may call other dynamic libraries. Hence, SME should be run in an environment that manages C++ and fortran versions as well as python packages. For this reason, we recommend running SME in a conda environment.
Create and maintain one conda environment for SME. Use that sme environment in every terminal window where you develop or run SME. Use other conda environments for projects.
Use environment¶
Activate the sme environment in each terminal window before working
with SME in that window. Activiating the sme environment adds a
(sme) prefix to your normal shell prompt. Create the environment
before using it.
$ conda activate sme
(sme) $
To stop using the sme environment in a terminal window, close the window or explicitly deactivate the current environment.
(sme) $ conda deactivate
$
Create environment¶
To create an environment for SME development:
1. Use bash shell because it is fully compatible with conda.
2. Install Miniconda or Anaconda. Miniconda includes a minimal set of python packages. Anaconda incudes many additional python packages that are not needed by SME. In either case, users will install additional packages as needed.
Installing conda typically prepends the conda bin directory
in the definition of PATH in ~/.bash_profile. Open
and begin working in a new terminal window, so that the new
PATH definition takes effect.
3. Clone
the SME repository on GitHub to a local SME directory.
$ git clone https://github.com/JeffValenti/SME.git
$ cd SME
SME$
4. Create a conda environment named sme using the
environment.yml file distributed with SME. The name of the
new environment (sme) is specified in environment.yml.
SME$ conda env create -f environment.yml
5. Install SME from the local repository. Activate the sme environment,
so that SME is installed in the sme environment, not the base
environment. Execute pip install from the top-level directory
of the local SME repository (typically sme). Use the –editable
option to keep the installed version synchronized with changes to the
local repository.
SME$ conda activate sme
(sme) SME$ pip install --editable .
Update environment¶
Periodically update packages in the sme environment to obtain the enviroment a new user or Travis CI would create.
$ conda activate sme
(sme) $ conda update
Recreate environment¶
Recreate the sme environment, if the environment.yml file
changes or to restore the sme environment to its canonical state.
First remove the existing sme environment.
(sme) $ conda deactivate
$ conda env remove --name sme
Then recreate the sme environment, starting with the conda env create step.
Supplement environment¶
If needed, use conda install to add additional packages while in the sme environment. Conda may have to install different versions of required packages to reconcile dependencies in the newly installed additional packages, but SME should still work.
$ conda activate sme
(sme) $ conda install <package>
If an additional package is not available via a conda channel, use pip install while in the sme environment. Package management is not as robust when using pip to install in a conda environment.
$ conda activate sme
(sme) $ pip install <package>
Additional packages will be available in the local sme environment,
but not in Travis CI or other user environments. To add packages for
all SME users, update the environment.yml file and recreate
the local sme environment.
Software Testing¶
SME uses the pytest framework to demonstrate that SME behaves as intended, despite inevitable changes to SME code, python modules, and the environment.
Unit Tests¶
Unit test code is located in the directory SME/test in files
named test_<module>.py. Each such file contains functions
named test_<purpose>. Each such function contains python
assert statements that test whether a particular code path
behaves as expected.
Run unit tests locally before committing code. Use the -v option to see results for each individual test function. Use the –cov=sme option to see what fraction of statements in each SME module are covered by unit tests. Unit tests should cover 100% of statements.
$ cd SME
SME$ conda activate sme
(sme) SME$ pytest -v --cov=sme --cov-report html
To see which specific statements are not covered, use a web browser
to view the file htmlcov/index.html and then click each
module name. On a mac, use open to view the file.
(sme) SME$ open htmlcov/index.html
Continuous Integration¶
The SME repository on GitHub is linked to the Travis CI
continuous integration service. Updating SME on GitHub causes
Travis CI to follow instructions in SME/.travis.yml.
These instructions build SME in one or more environments (e.g.,
linux, osx) and run pytest. When the tests complete,
GitHub indicates the result with a green check mark (pass) or
a red ‘X’ (fail). Resolve failures before merging a pull request
or making a release.
Test Data¶
Test data for test_vald() were generated using the VALD3
extract stellar feature and the following parameter values.
| VALD job date | 12/30/18 | 12/30/18 | 12/30/18 | 12/30/18 |
| VALD job number | 045169 | 045170 | 045174 | 045175 |
| Starting wavelength | 6562 | 656.0188 | 49958.83 | 1999 |
| Ending wavelength | 6567 | 656.5186 | 50025.01 | 2001 |
| Detection threshold | 0.001 | 0.001 | 0.001 | 0.001 |
| Microturbulence | 0 | 0 | 0 | 0 |
| Effective temperature | 5750 | 5750 | 3500 | 3500 |
| Log surface gravity | 4.5 | 4.5 | 5.0 | 5.0 |
| Extraction format | long | short | long | short |
| Energy level units | eV | cm-1 | cm-1 | eV |
| Medium | vacuum | air | vacuum | air |
| Wavelength units | Angstrom | nm | cm-1 | Angstrom |
| Van der Waals syntax | extended | extended | extended | extended |
| Isotopic scaling | on | on | off | off |
Documentation¶
SME uses the Sphinx documentation builder to translate
reStructuredText source files into various output formats,
including HTML and PDF. SME documentation source is located in
the directory SME/docs. The master document is
SME/docs/index.rst. Additional source files are in the
subdirectory SME/docs/content. SME has documentation
for users and for developers.
Online¶
The SME repository on GitHub is linked to the readthedocs online documentation service. Updating SME on GitHub causes readthedocs to rebuild and publish the latest SME documentation from source.
Local¶
Use make to build a local copy of the documentation in the
directory SME/docs/_build. Use the argument html to build
HTML documentation and latexpdf to build PDF documentation.
$ cd SME/docs
SME$ conda activate sme
(sme) SME$ make html
(sme) SME$ make latexpdf
Use a web browser to view the file _build/html/index.html.
Use a PDF browser to view the file _build/latex/SME.pdf.
On a mac, use open to view either type of output format.
(sme) SME$ open _build/html/index.html
(sme) SME$ open _build/latex/SME.pdf