crp/OpenMC
1
0
Fork 0
mirror of https://github.com/openmc-dev/openmc.git synced 2026-07-26 21:25:36 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

adding back files to be reviewed

Browse source
This commit is contained in:
Paul Romano 2019-10-28 11:55:45 -05:00
parent ae28233110
commit bc09d1ef55
1244 changed files with 301904 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

129
docs/source/devguide/contributing.rst Normal file
View file

@ -0,0 +1,129 @@
.. _devguide_contributing:
======================
Contributing to OpenMC
======================
Thank you for considering contributing to OpenMC! We look forward to welcoming
new members to the community and will do our best to help you get up to speed.
The purpose of this section is to document how the project is managed: how
contributions (bug fixes, enhancements, new features) are made, how they are
evaluated, who is permitted to merge pull requests, and what happens in the
event of disagreements. Once you have read through this section, the
:ref:`devguide_workflow` section outlines the actual mechanics of making a
contribution (forking, submitting a pull request, etc.).
The goal of our governance model is to:
- Encourage new contributions.
- Encourage contributors to remain involved.
- Avoid unnecessary processes and bureaucracy whenever possible.
- Create a transparent decision making process which makes it clear how
contributors can be involved in decision making.
Overview
--------
OpenMC uses a liberal contribution model for project governance. Anyone involved
in development in a non-trivial capacity is given an opportunity to influence
the direction of the project. Project decisions are made through a
consensus-seeking process rather than by voting.
Terminology
-----------
- A *Contributor* is any individual creating or commenting on an issue or pull
request.
- A *Committer* is a subset of contributors who are authorized to review and
merge pull requests.
- The *TC* (Technical Committee) is a group of committers who have the authority
to make decisions on behalf of the project team in order to resolve disputes.
- The *Project Lead* is a single individual who has the authority to make a final
decision when the TC is unable to reach consensus.
Contribution Process
--------------------
Any change to the OpenMC repository must be made through a pull request (PR).
This applies to all changes to documentation, code, binary files, etc. Even long
term committers and TC members must use pull requests.
No pull request may be merged without being independently reviewed.
For non-trivial contributions, pull requests should not be merged for at least
36 hours to ensure that contributors in other timezones have time to review.
Consideration should be given to weekends and other holiday periods to ensure
active committers have reasonable time to become involved in the discussion and
review process if they wish. Any committer may request that the review period be
extended if they are unable to review the change within 36 hours.
During review, a committer may request that a specific contributor who is most
versed in a particular area review the PR before it can be merged.
A pull request can be merged by any committer, but only if no objections are
raised by any other committer. In the case of an objection being raised, all
involved committers should seek consensus through discussion and compromise.
In the case of an objection being raised in a pull request by another committer,
all involved committers should seek to arrive at a consensus by way of
addressing concerns being expressed through discussion, compromise on the
proposed change, or withdrawal of the proposed change.
If objections to a PR are made and committers cannot reach a consensus on how to
proceed, the decision is escalated to the TC. TC members should regularly
discuss pending contributions in order to find a resolution. It is expected that
only a small minority of issues be brought to the TC for resolution and that
discussion and compromise among committers be the default resolution mechanism.
Becoming a Committer
--------------------
All contributors who make a non-trivial contribution will be added as a
committer in a timely manner. Committers are expected to follow this policy.
TC Process
----------
Any issues brought to the TC will be addressed among the committee with a
consensus-seeking process. The group tries to find a resolution that has no
objections among TC members. If a consensus cannot be reached, the Project Lead
has the ultimate authority to make a final decision. It is expected that the
majority of decisions made by the TC are via a consensus seeking process and
that the Project Lead intercedes only as a last resort.
Resolution may involve returning the issue to committers with suggestions on how
to move forward towards a consensus.
Members can be added to the TC at any time. Any committer can nominate another
committer to the TC and the TC uses its standard consensus seeking process to
evaluate whether or not to add this new member. Members who do not participate
consistently at the level of a majority of the other members are expected to
resign.
In the event that the Project Lead resigns or otherwise steps down, the TC uses
a consensus seeking process to choose a new Project Lead.
Leadership Team
---------------
The TC consists of the following individuals:
- `Paul Romano <https://github.com/paulromano>`_
- `Sterling Harper <https://github.com/smharper>`_
- `Adam Nelson <https://github.com/nelsonag>`_
- `Benoit Forget <https://github.com/bforget>`_
The Project Lead is Paul Romano.
Next Steps
----------
If you are interested in working on a specific feature or helping to address
outstanding issues, consider joining the developer's `mailing list
<https://groups.google.com/forum/#!forum/openmc-dev>`_ and/or `Slack community
<https://openmc.slack.com/signup>`_. Note that some issues have specifically
been labeled as good for `first-time contributors
<https://github.com/openmc-dev/openmc/issues?q=is%3Aopen+is%3Aissue+label%3AFirst-Timers-Only>`_.
Once you're at the point of writing code, make sure your read through the
:ref:`devguide_workflow` section to understand the mechanics of making pull
requests and what is expected during code reviews.

45
docs/source/devguide/docbuild.rst Normal file
View file

@ -0,0 +1,45 @@
.. _devguide_docbuild:
=============================
Building Sphinx Documentation
=============================
In order to build the documentation in the ``docs`` directory, you will need to
have the `Sphinx <https://www.sphinx-doc.org/en/master/>`_ third-party Python
package. The easiest way to install Sphinx is via pip:
.. code-block:: sh
pip install sphinx
Additionally, you will need several Sphinx extensions that can be installed
directly with pip:
.. code-block:: sh
pip install sphinx-numfig
pip install sphinxcontrib-katex
pip install sphinxcontrib-svg2pdfconverter
-----------------------------------
Building Documentation as a Webpage
-----------------------------------
To build the documentation as a webpage (what appears at
https://docs.openmc.org), simply go to the ``docs`` directory and run:
.. code-block:: sh
make html
-------------------------------
Building Documentation as a PDF
-------------------------------
To build PDF documentation, you will need to have a LaTeX distribution installed
on your computer. Once you have a LaTeX distribution installed, simply go to the
``docs`` directory and run:
.. code-block:: sh
make latexpdf

56
docs/source/devguide/docker.rst Normal file
View file

@ -0,0 +1,56 @@
.. _devguide_docker:
======================
Deployment with Docker
======================
OpenMC can be easily deployed using `Docker <https://www.docker.com/>`_ on any
Windows, Mac or Linux system. With Docker running, execute the following
command in the shell to build a `Docker image`_ called ``debian/openmc:latest``:
.. code-block:: sh
docker build -t debian/openmc:latest https://github.com/openmc-dev/openmc.git#develop
.. note:: This may take 5 -- 10 minutes to run to completion.
This command will execute the instructions in OpenMC's ``Dockerfile`` to
build a Docker image with OpenMC installed. The image includes OpenMC with
MPICH and parallel HDF5 in the ``/opt/openmc`` directory, and
`Miniconda3 <https://conda.io/miniconda.html>`_ with all of the Python
pre-requisites (NumPy, SciPy, Pandas, etc.) installed. The
`NJOY2016 <https://www.njoy21.io/NJOY2016/>`_ codebase is installed in
``/opt/NJOY2016`` to support full functionality and testing of the
``openmc.data`` Python module. The publicly available nuclear data libraries
necessary to run OpenMC's test suite -- including NNDC and WMP cross sections
and ENDF data -- are in the ``/opt/openmc/data directory``, and the
corresponding :envvar:`OPENMC_CROSS_SECTIONS`,
:envvar:`OPENMC_MULTIPOLE_LIBRARY`, and :envvar:`OPENMC_ENDF_DATA`
environment variables are initialized.
After building the Docker image, you can run the following to see the names of
all images on your machine, including ``debian/openmc:latest``:
.. code-block:: sh
docker image ls
Now you can run the following to create a `Docker container`_ called
``my_openmc`` based on the ``debian/openmc:latest`` image:
.. code-block:: sh
docker run -it --name=my_openmc debian/openmc:latest
This command will open an interactive shell running from within the
Docker container where you have access to use OpenMC.
.. note:: The ``docker run`` command supports many
`options <https://docs.docker.com/engine/reference/commandline/run/>`_
for spawning containers -- including `mounting volumes`_ from the
host filesystem -- which many users will find useful.
.. _Docker image: https://docs.docker.com/engine/reference/commandline/images/
.. _Docker container: https://www.docker.com/resources/what-container
.. _options: https://docs.docker.com/engine/reference/commandline/run/
.. _mounting volumes: https://docs.docker.com/storage/volumes/

21
docs/source/devguide/index.rst Normal file
View file

@ -0,0 +1,21 @@
.. _devguide:
=================
Developer's Guide
=================
Welcome to the OpenMC Developer's Guide! This guide documents how contributions
are made to OpenMC, what style rules exist for the code, how to run tests, and
other related topics.
.. toctree::
:numbered:
:maxdepth: 2
contributing
workflow
styleguide
tests
user-input
docbuild
docker

241
docs/source/devguide/styleguide.rst Normal file
View file

@ -0,0 +1,241 @@
.. _devguide_styleguide:
======================
Style Guide for OpenMC
======================
In order to keep the OpenMC code base consistent in style, this guide specifies
a number of rules which should be adhered to when modified existing code or
adding new code in OpenMC.
---
C++
---
Indentation
-----------
Use two spaces per indentation level.
Miscellaneous
-------------
Follow the `C++ Core Guidelines`_ except when they conflict with another
guideline listed here. For convenience, many important guidelines from that
list are repeated here.
Conform to the C++14 standard.
Always use C++-style comments (``//``) as opposed to C-style (``/**/``). (It
is more difficult to comment out a large section of code that uses C-style
comments.)
Do not use C-style casting. Always use the C++-style casts ``static_cast``,
``const_cast``, or ``reinterpret_cast``. (See `ES.49 <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es49-if-you-must-use-a-cast-use-a-named-cast>`_)
Source Files
------------
Use a ``.cpp`` suffix for code files and ``.h`` for header files.
Header files should always use include guards with the following style (See
`SF.8 <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf8-use-include-guards-for-all-h-files>`_):
.. code-block:: C++
#ifndef OPENMC_MODULE_NAME_H
#define OPENMC_MODULE_NAME_H
namespace openmc {
...
content
...
}
#endif // OPENMC_MODULE_NAME_H
Avoid hidden dependencies by always including a related header file first,
followed by C/C++ library includes, other library includes, and then local
includes. For example:
.. code-block:: C++
// foo.cpp
#include "foo.h"
#include <cstddef>
#include <iostream>
#include <vector>
#include "hdf5.h"
#include "pugixml.hpp"
#include "error.h"
#include "random_lcg.h"
Naming
------
Struct and class names should be CamelCase, e.g. ``HexLattice``.
Functions (including member functions) should be lower-case with underscores,
e.g. ``get_indices``.
Local variables, global variables, and struct/class member variables should be
lower-case with underscores (e.g., ``n_cells``) except for physics symbols that
are written differently by convention (e.g., ``E`` for energy). Data members of
classes (but not structs) additionally have trailing underscores (e.g.,
``a_class_member_``).
The following conventions are used for variables with short names:
- ``d`` stands for "distance"
- ``E`` stands for "energy"
- ``p`` stands for "particle"
- ``r`` stands for "position"
- ``rx`` stands for "reaction"
- ``u`` stands for "direction"
- ``xs`` stands for "cross section"
All classes and non-member functions should be declared within the ``openmc``
namespace. Global variables must be declared in a namespace nested within the
``openmc`` namespace. The following sub-namespaces are in use:
- ``openmc::data``: Fundamental nuclear data (cross sections, multigroup data,
decay constants, etc.)
- ``openmc::model``: Variables related to geometry, materials, and tallies
- ``openmc::settings``: Global settings / options
- ``openmc::simulation``: Variables used only during a simulation
Accessors and mutators (get and set functions) may be named like
variables. These often correspond to actual member variables, but this is not
required. For example, ``int count()`` and ``void set_count(int count)``.
Variables declared constexpr or const that have static storage duration (exist
for the duration of the program) should be upper-case with underscores,
e.g., ``SQRT_PI``.
Use C++-style declarator layout (see `NL.18
<http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#nl18-use-c-style-declarator-layout>`_):
pointer and reference operators in declarations should be placed adject to the
base type rather than the variable name. Avoid declaring multiple names in a
single declaration to avoid confusion:
.. code-block:: C++
T* p; // good
T& p; // good
T *p; // bad
T* p, q; // misleading
Curly braces
------------
For a class declaration, the opening brace should be on the same line that
lists the name of the class.
.. code-block:: C++
class Matrix {
...
};
For a function definition, the opening and closing braces should each be on
their own lines. This helps distinguish function code from the argument list.
If the entire function fits on one or two lines, then the braces can be on the
same line. e.g.:
.. code-block:: C++
return_type function(type1 arg1, type2 arg2)
{
content();
}
return_type
function_with_many_args(type1 arg1, type2 arg2, type3 arg3,
type4 arg4)
{
content();
}
int return_one() {return 1;}
int return_one()
{return 1;}
For a conditional, the opening brace should be on the same line as the end of
the conditional statement. If there is a following ``else if`` or ``else``
statement, the closing brace should be on the same line as that following
statement. Otherwise, the closing brace should be on its own line. A one-line
conditional can have the closing brace on the same line or it can omit the
braces entirely e.g.:
.. code-block:: C++
if (condition) {
content();
}
if (condition1) {
content();
} else if (condition 2) {
more_content();
} else {
further_content();
}
if (condition) {content()};
if (condition) content();
For loops similarly have an opening brace on the same line as the statement and
a closing brace on its own line. One-line loops may have the closing brace on
the same line or omit the braces entirely.
.. code-block:: C++
for (int i = 0; i < 5; i++) {
content();
}
for (int i = 0; i < 5; i++) {content();}
for (int i = 0; i < 5; i++) content();
Documentation
-------------
Classes, structs, and functions are to be annotated for the `Doxygen
<http://www.doxygen.nl/>`_ documentation generation tool. Use the ``\`` form of
Doxygen commands, e.g., ``\brief`` instead of ``@brief``.
------
Python
------
Style for Python code should follow PEP8_.
Docstrings for functions and methods should follow numpydoc_ style.
Python code should work with Python 3.4+.
Use of third-party Python packages should be limited to numpy_, scipy_,
matplotlib_, pandas_, and h5py_. Use of other third-party packages must be
implemented as optional dependencies rather than required dependencies.
Prefer pathlib_ when working with filesystem paths over functions in the os_
module or other standard-library modules. Functions that accept arguments that
represent a filesystem path should work with both strings and Path_ objects.
.. _C++ Core Guidelines: http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
.. _numpy: https://numpy.org/
.. _scipy: https://www.scipy.org/
.. _matplotlib: https://matplotlib.org/
.. _pandas: https://pandas.pydata.org/
.. _h5py: https://www.h5py.org/
.. _pathlib: https://docs.python.org/3/library/pathlib.html
.. _os: https://docs.python.org/3/library/os.html
.. _Path: https://docs.python.org/3/library/pathlib.html#pathlib.Path

89
docs/source/devguide/tests.rst Normal file
View file

@ -0,0 +1,89 @@
.. _devguide_tests:
==========
Test Suite
==========
The OpenMC test suite consists of two parts, a regression test suite and a unit
test suite. The regression test suite is based on regression or integrated
testing where different types of input files are configured and the full OpenMC
code is executed. Results from simulations are compared with expected
results. The unit tests are primarily intended to test individual
functions/classes in the OpenMC Python API.
Prerequisites
-------------
- The test suite relies on the third-party `pytest <https://pytest.org>`_
package. To run either or both the regression and unit test suites, it is
assumed that you have OpenMC fully installed, i.e., the :ref:`scripts_openmc`
executable is available on your :envvar:`PATH` and the :mod:`openmc` Python
module is importable. In development where it would be onerous to continually
install OpenMC every time a small change is made, it is recommended to install
OpenMC in development/editable mode. With setuptools, this is accomplished by
running::
python setup.py develop
or using pip (recommended)::
pip install -e .[test]
- The test suite requires a specific set of cross section data in order for
tests to pass. A download URL for the data that OpenMC expects can be found
within ``tools/ci/download-xs.sh``.
- In addition to the HDF5 data, some tests rely on ENDF files. A download URL
for those can also be found in ``tools/ci/download-xs.sh``.
- Some tests require `NJOY <https://www.njoy21.io/NJOY2016>`_ to preprocess
cross section data. The test suite assumes that you have an ``njoy``
executable available on your :envvar:`PATH`.
Running Tests
-------------
To execute the test suite, go to the ``tests/`` directory and run::
pytest
If you want to collect information about source line coverage in the Python API,
you must have the `pytest-cov <https://pypi.python.org/pypi/pytest-cov>`_ plugin
installed and run::
pytest --cov=../openmc --cov-report=html
Generating XML Inputs
---------------------
Many of the regression tests rely on the Python API to build an appropriate
model. However, it can sometimes be desirable to work directly with the XML
input files rather than having to run a script in order to run the problem/test.
To build the input files for a test without actually running the test, you can
run::
pytest --build-inputs <name-of-test>
Adding Tests to the Regression Suite
------------------------------------
To add a new test to the regression test suite, create a sub-directory in the
``tests/regression_tests/`` directory. To configure a test you need to add the
following files to your new test directory:
* OpenMC input XML files, if they are not generated through the Python API
* **test.py** - Python test driver script; please refer to other tests to
see how to construct. Any output files that are generated during testing
must be removed at the end of this script.
* **inputs_true.dat** - ASCII file that contains Python API-generated XML
files concatenated together. When the test is run, inputs that are
generated are compared to this file.
* **results_true.dat** - ASCII file that contains the expected results from
the test. The file *results_test.dat* is compared to this file during the
execution of the python test driver script. When the above files have been
created, generate a *results_test.dat* file and copy it to this name and
commit. It should be noted that this file should be generated with basic
compiler options during openmc configuration and build (e.g., no MPI, no
debug/optimization).
In addition to this description, please see the various types of tests that are
already included in the test suite to see how to create them. If all is
implemented correctly, the new test will automatically be discovered by pytest.

71
docs/source/devguide/user-input.rst Normal file
View file

@ -0,0 +1,71 @@
.. _devguide_user_input:
=========================
Making User Input Changes
=========================
Users are encouraged to use OpenMC's :ref:`pythonapi` to build XML files that
the OpenMC solver then reads during the initialization phase. Thus, to modify,
add, or remove user input options, changes must be made both within the Python
API and the C++ source that reads XML files produced by the Python API. The
following steps should be followed to make changes to user input:
1. Determine the Python class you need to change. For example, if you are adding
a new setting, you probably want to change the :class:`openmc.Settings`
class. If you are adding a new surface type, you would need to create a
subclass of :class:`openmc.Surface`.
2. To add a new option, the class will need a `property attribute`_. For
example, if you wanted to add a "fast_mode" setting, you would need two
methods that look like:
.. code-block:: python
@property
def fast_mode(self):
...
@fast_mode.setter
def fast_mode(self, fast_mode):
...
3. Make sure that when an instance of the class is exported to XML (usually
through a ``export_to_xml()`` or ``to_xml_element()`` method), a new element
is written to the appropriate file. OpenMC uses the
:mod:`xml.etree.ElementTree` API, so refer to the documentation of that
module for guidance on creating elements/attributes.
4. Make sure that your input can be categorized as one of the datatypes from
`XML Schema Part 2`_ and that parsing of the data appropriately reflects
this. For example, for a boolean_ value, true can be represented either by
"true" or by "1".
5. Now that you're done with the Python side, you need to make modifications to
the C++ codebase. Make appropriate changes in source files (e.g.,
settings.cpp). You should use convenience functions defined by
xml_interface.cpp.
6. If you've made changes in the geometry or materials, make sure they are
written out to the statepoint or summary files and that the
:class:`openmc.StatePoint` and :class:`openmc.Summary` classes read them in.
7. Finally, a set of `RELAX NG`_ schemas exists that enables validation of input
files. You should modify the RELAX NG schema for the file you changed. The
easiest way to do this is to change the `compact syntax`_ file
(e.g. ``src/relaxng/geometry.rnc``) and then convert it to regular XML syntax
using trang_::
trang geometry.rnc geometry.rng
For most user input additions and changes, it is simple enough to follow a
"monkey see, monkey do" approach. When in doubt, contact your nearest OpenMC
developer or send a message to the `developers mailing list`_.
.. _property attribute: https://docs.python.org/3.6/library/functions.html#property
.. _XML Schema Part 2: http://www.w3.org/TR/xmlschema-2/
.. _boolean: http://www.w3.org/TR/xmlschema-2/#boolean
.. _RELAX NG: http://relaxng.org/
.. _compact syntax: http://relaxng.org/compact-tutorial-20030326.html
.. _trang: http://www.thaiopensource.com/relaxng/trang.html
.. _developers mailing list: https://groups.google.com/forum/?fromgroups=#!forum/openmc-dev

132
docs/source/devguide/workflow.rst Normal file
View file

@ -0,0 +1,132 @@
.. _devguide_workflow:
====================
Development Workflow
====================
Anyone wishing to make contributions to OpenMC should be fully acquianted and
comfortable working with git_ and GitHub_. We assume here that you have git
installed on your system, have a GitHub account, and have setup SSH keys to be
able to create/push to repositories on GitHub.
Overview
--------
Development of OpenMC relies heavily on branching; specifically, we use a
branching model sometimes referred to as `git flow`_. If you plan to contribute
to OpenMC development, we highly recommend that you read the linked blog post to
get a sense of how the branching model works. There are two main branches that
always exist: *master* and *develop*. The *master* branch is a stable branch
that contains the latest release of the code. The *develop* branch is where any
ongoing development takes place prior to a release and is not guaranteed to be
stable. When the development team decides that a release should occur, the
*develop* branch is merged into *master*.
All new features, enhancements, and bug fixes should be developed on a branch
that branches off of *develop*. When the feature is completed, a `pull request`_
is initiated on GitHub that is then reviewed by a committer. If the pull request
is satisfactory, it is then merged into *develop*. Note that a committer may not
review their own pull request (i.e., an independent code review is required).
Code Review Criteria
--------------------
In order to be considered suitable for inclusion in the *develop* branch, the
following criteria must be satisfied for all proposed changes:
- Changes have a clear purpose and are useful.
- Compiles and passes all tests under multiple build configurations (This is
checked by Travis CI).
- If appropriate, test cases are added to regression or unit test suites.
- No memory leaks (checked with valgrind_).
- Conforms to the OpenMC `style guide`_.
- No degradation of performance or greatly increased memory usage. This is not a
hard rule -- in certain circumstances, a performance loss might be acceptable
if there are compelling reasons.
- New features/input are documented.
- No unnecessary external software dependencies are introduced.
Contributing
------------
Now that you understand the basic development workflow, let's discuss how an
individual to contribute to development. Note that this would apply to both new
features and bug fixes. The general steps for contributing are as follows:
1. Fork the main openmc repository from `openmc-dev/openmc`_. This will create a
repository with the same name under your personal account. As such, you can
commit to it as you please without disrupting other developers.
.. image:: ../_images/fork.png
2. Clone your fork of OpenMC and create a branch that branches off of *develop*:
.. code-block:: sh
git clone git@github.com:yourusername/openmc.git
cd openmc
git checkout -b newbranch develop
3. Make your changes on the new branch that you intend to have included in
*develop*. If you have made other changes that should not be merged back,
ensure that those changes are made on a different branch.
4. Issue a pull request from GitHub and select the *develop* branch of
openmc-dev/openmc as the target.
At a minimum, you should describe what the changes you've made are and why
you are making them. If the changes are related to an oustanding issue, make
sure it is cross-referenced.
5. A committer will review your pull request based on the criteria
above. Any issues with the pull request can be discussed directly on the pull
request page itself.
6. After the pull request has been thoroughly vetted, it is merged back into the
*develop* branch of openmc-dev/openmc.
Private Development
-------------------
While the process above depends on the fork of the OpenMC repository being
publicly available on GitHub, you may also wish to do development on a private
repository for research or commercial purposes. The proper way to do this is to
create a complete copy of the OpenMC repository (not a fork from GitHub). The
private repository can then either be stored just locally or in conjunction with
a private repository on Github (this requires a `paid plan`_). Alternatively,
`Bitbucket`_ offers private repositories for free. If you want to merge some
changes you've made in your private repository back to openmc-dev/openmc
repository, simply follow the steps above with an extra step of pulling a branch
from your private repository into a public fork.
.. _devguide_editable:
Working in "Development" Mode
-----------------------------
If you are making changes to the Python API during development, it is highly
suggested to install the Python API in development/editable mode using
pip_. From the root directory of the OpenMC repository, run:
.. code-block:: sh
pip install -e .[test]
This installs the OpenMC Python package in `"editable" mode
<https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_ so
that 1) it can be imported from a Python interpreter and 2) any changes made are
immediately reflected in the installed version (that is, you don't need to keep
reinstalling it). While the same effect can be achieved using the
:envvar:`PYTHONPATH` environment variable, this is generally discouraged as it
can interfere with virtual environments.
.. _git: http://git-scm.com/
.. _GitHub: https://github.com/
.. _git flow: http://nvie.com/git-model
.. _valgrind: http://valgrind.org/
.. _style guide: https://docs.openmc.org/en/latest/devguide/styleguide.html
.. _pull request: https://help.github.com/articles/using-pull-requests
.. _openmc-dev/openmc: https://github.com/openmc-dev/openmc
.. _paid plan: https://github.com/plans
.. _Bitbucket: https://bitbucket.org
.. _pip: https://pip.pypa.io/en/stable/