Contributing to Dymos¶
Dymos is open-source software and the developers welcome collaboration with the community on finding and fixing bugs or requesting and implementing new features.
Found a bug in Dymos?¶
If you believe you've found a bug in Dymos, submit a new issue. If at all possible, please include a functional code example which demonstrates the issue (the expected behavior vs. the actual behavior).
Fixed a bug in Dymos?¶
If you believe you have a fix for an existing bug in Dymos, please submit the fix as pull request. Under the "related issues" section of the pull request template, include the issue resolved by the pull request using Github's referencing syntax. When submitting a bug-fix pull request, please include a unit test that demonstrates the corrected behavior. This will prevent regressions in the future.
Need new functionality in Dymos?¶
If you would like to have new functionality that currently doesn't exist in Dymos, please submit your request via the Dymos issues on Github. The Dymos development team is small and we can't promise that we'll add every requested capability, but we'll happily have a discussion and try to accommodate reasonable requests that fit within the goals of the library.
Adding new examples¶
Adding new examples are a great way to contribute to Dymos. They're a great introduction to the Dymos development process, and examples provide a great way for users to learn to apply Dymos in new applications. Submit new examples via the Dymos issues on Github. New examples should do the following:
- Include a new directory under the
dymos/examples
directory. - A unittest should be included in a
doc
subfolder within the example directory. - The unittest method should be self-contained (it should include all imports necessary to run the example).
- If you want to include output and/or plots from the example in the documentation (highly recommended), decorate the test with the
@dymos.utils.doc_utils.save_for_docs
decorator. This will save the text and plot outputs from the test for inclusion in the Dymos documentation. - A new markdown file should be added under
mkdocs/docs/examples/<example name>
within the Dymos repository.
The following mkdocs macros have been developed to make it easier to document examples.
inline_source
Includes the text from the test method as a code block in the documentation. For example, the brachistochrone example source code is included using the following in the markdown documented.
{{ inline_source('dymos.examples.brachistochrone.doc.test_doc_brachistochrone.TestBrachistochrone.test_brachistochrone',
include_def=False,
include_docstring=False,
indent_level=0)
}}
Arguments include_def
and include_docstring
dictate whether the method declaration and docstring are included in the markdown documentation, respectively.
The argument indent_level
can be used to control the level of indentation added to the example, if necessary.
embed_test_output
Using the @save_for_docs
decorator on a test method will save its output and any plots generated to subdirectory named _outputs
under the test's doc
directory.
Using embed_test_output
will grab the output from the test and include it in the documentation as a block.
For example, from the brachistochrone documentation:
{{ embed_test_output('dymos.examples.brachistochrone.doc.test_doc_brachistochrone.TestBrachistochrone.test_brachistochrone') }}
embed_test_plot
Similarly, the plots from the example can be included using the embed_test_plot
macro:
{{ embed_test_plot('dymos.examples.brachistochrone.doc.test_doc_brachistochrone.TestBrachistochrone.test_brachistochrone',
alt_text='The solution to the Brachistochrone problem',
index=1) }}
Here alt_text
is the text displayed when cursor is over the image, and index
is the index of the plot figure from the test (default is 1, this index starts at 1).
Running Tests¶
Dymos tests can be run with any test runner such as nosetests or pytest. However, due to some MPI-specific tests in our examples, we prefer our testflo package. The testflo utility can be installed using
python -m pip install testflo
Testflo can be invoked from the top-level Dymos directory with:
testflo .
With pyoptsparse correctly installed and things working correctly, the tests should conclude after several minutes with a message like the following: The lack of MPI capability or pyoptsparse will cause additional tests to be skipped.
The following tests were skipped:
test_command_line.py:TestCommandLine.test_ex_brachistochrone_reset_grid
OK
Passed: 450
Failed: 0
Skipped: 1
Ran 451 tests using 2 processes