Skip to content

Commit 5de08f9

Browse files
Jacob-Stevens-HaasJacob-Stevens-Haas
committed
DOC: Add contributing guide, remove duplicated content from README.md
Also bump python version and add myself to a few repo email links
1 parent dcf84dc commit 5de08f9

File tree

5 files changed

+231
-144
lines changed

5 files changed

+231
-144
lines changed

‎README.rst‎

Lines changed: 11 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -98,64 +98,19 @@ PySINDy provides numerous other features not shown here. We recommend the `featu
9898
Installation
9999
------------
100100

101-
Installing with pip
102-
^^^^^^^^^^^^^^^^^^^
103-
104-
If you are using Linux or macOS you can install PySINDy with pip:
105-
106-
.. code-block:: bash
107-
108-
pip install pysindy
109-
110-
Installing from source
111-
^^^^^^^^^^^^^^^^^^^^^^
112-
First clone this repository:
113-
114-
.. code-block:: bash
115-
116-
git clone https://github.com/dynamicslab/pysindy.git
117-
118-
Then, to install the package, run
119-
120-
.. code-block:: bash
121-
122-
pip install .
123-
124-
If you do not have root access, you should add the ``--user`` option to the above lines.
125-
126-
Caveats
127-
^^^^^^^
128-
129-
To run the unit tests, or example notebooks, you should install the dev-dependencies with:
130-
131-
.. code-block:: bash
101+
The preferred way to install is with pip or conda e.g. ``pip install pysindy``
132102

133-
pip install pysindy[dev]
103+
You may have to add ``--user`` option to the above lines.
104+
Pysindy also provides several extras:
134105

135-
or if you are installing from a local copy
106+
cvxpy
107+
Convex optimizer ``SR3`` and subclasses
136108

137-
.. code-block:: bash
109+
miosr
110+
Branch-and-bound optimizer for L0-constraint, ``MIOSR``
138111

139-
pip install .[dev]
140-
141-
To build a local copy of the documentation, you should install the docs-dependencies with:
142-
143-
.. code-block:: bash
144-
145-
pip install pysindy[docs]
146-
147-
If you are looking to use convex optimization provided by `cvxpy <https://github.com/cvxpy/cvxpy>`__, then you have to install
148-
149-
.. code-block:: bash
150-
151-
pip install pysindy[cvxpy]
152-
153-
to utilize Mixed-Integer Optimized Sparse Regression (MIOSR) via `GurobiPy <https://pypi.org/project/gurobipy/>`__, you
154-
require
155-
156-
.. code-block:: bash
157-
158-
pip install pysindy[miosr]
112+
sbr
113+
Bayesian regression optimizer yielding posteriors, ``SBR``.
159114

160115

161116
Documentation
@@ -171,95 +126,9 @@ This flow chart summarizes how ``PySINDy`` users can start with a dataset and sy
171126
Community guidelines
172127
--------------------
173128

174-
Contributing examples
129+
Contributing
175130
^^^^^^^^^^^^^^^^^^^^^
176-
We love seeing examples of PySINDy being used to solve interesting problems! If you would like to contribute an example to the documentation, reach out to us by creating an issue.
177-
178-
Examples are external repositories that
179-
`follow a structure <https://github.com/dynamicslab/pysindy-example>`_ that pysindy
180-
knows how to incorporate into its documentation build. They tend to be pinned to
181-
a set of dependencies and may not be kept up to date with breaking API changes.
182-
183-
The linked repository has information on how to set up your example. To PR the example
184-
into this repository, (a) edit examples/external.yml and examples/README.rst with your
185-
repository information and (b) verify your own build passes in your repository,
186-
including publishing on github pages. If you want to keep your example up to date with
187-
the pysindy main branch, (c) add your repository information to the ``notify-experiments``
188-
workflow so that pysindy will trigger your notebooks to be run in CI in your own repo.
189-
This will require adding a
190-
`fine-grained PAT <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens>`_
191-
with the permissions ``contents: read & write`` and ``metadata: read only`` to the
192-
pysindy GH secrets. Alternatively, you can just trigger your builds based on cron timing.
193-
See the pysindy experiments repo for more information.
194-
195-
196-
Contributing code
197-
^^^^^^^^^^^^^^^^^
198-
We welcome contributions to PySINDy. To contribute a new feature please submit a pull request. To get started we recommend installing an editable ``dev`` version from a local clone via
199-
200-
.. code-block:: bash
201-
202-
pip install -e .[dev]
203-
204-
This will allow you to run unit tests and automatically format your code. To be accepted your code should conform to PEP8 and pass all unit tests. Code can be tested by invoking
205-
206-
.. code-block:: bash
207-
208-
pytest
209-
210-
We recommend using ``pre-commit`` to format your code. The easiest approach is to install pre-commit via
211-
212-
.. code-block:: bash
213-
214-
pre-commit install
215-
216-
After which pre-commit will automatically check all future commits. Once you have staged changes to commit
217-
218-
.. code-block:: bash
219-
220-
git add path/to/changed/file.py
221-
222-
Pre-commit will then automatically run all checks against your committed code. If you want to trigger this manually, you can run the following to automatically reformat your staged code
223-
224-
.. code-block:: bash
225-
226-
pre-commit
227-
228-
Note that you will then need to re-stage any changes ``pre-commit`` made to your code.
229-
230-
Building documentation requires the ``docs`` dependencies, which can be installed with either
231-
232-
.. code-block:: bash
233-
234-
pip install pysindy[docs]
235-
236-
or with
237-
238-
.. code-block:: bash
239-
240-
pip install .[docs]
241-
242-
for a local clone of the repository. Once installed, run
243-
244-
.. code-block:: bash
245-
246-
python -m sphinx -TEb html -d _build/doctrees -D language=en . ./build
247-
248-
Or check the build step in the most recent CI run or [RTD build](https://readthedocs.org/projects/pysindy/builds/).
249-
250-
There are a number of SINDy variants and advanced functionality that would be great to implement in future releases:
251-
252-
1. Bayesian SINDy, for instance that from Hirsh, Seth M., David A. Barajas-Solano, and J. Nathan Kutz. "Sparsifying Priors for Bayesian Uncertainty Quantification in Model Discovery." arXiv preprint arXiv:2107.02107 (2021).
253-
254-
2. Tensor SINDy, using the methods in Gelß, Patrick, et al. "Multidimensional approximation of nonlinear dynamical systems." Journal of Computational and Nonlinear Dynamics 14.6 (2019).
255-
256-
3. Stochastic SINDy, using the methods in Brückner, David B., Pierre Ronceray, and Chase P. Broedersz. "Inferring the dynamics of underdamped stochastic systems." Physical review letters 125.5 (2020): 058103.
257-
258-
4. Integration of PySINDy with a Python model-predictive control (MPC) code.
259-
260-
5. The PySINDy weak formulation is based on the work in Reinbold, Patrick AK, Daniel R. Gurevich, and Roman O. Grigoriev. "Using noisy or incomplete data to discover models of spatiotemporal dynamics." Physical Review E 101.1 (2020): 010203. It might be useful to additionally implement the weak formulation from Messenger, Daniel A., and David M. Bortz. "Weak SINDy for partial differential equations." Journal of Computational Physics (2021): 110525. The weak formulation in PySINDy is also fairly slow and computationally intensive, so finding ways to speed up the code would be great.
261-
262-
6. The blended conditional gradients (BCG) algorithm for solving the constrained LASSO problem, Carderera, Alejandro, et al. "CINDy: Conditional gradient-based Identification of Non-linear Dynamics--Noise-robust recovery." arXiv preprint arXiv:2101.02630 (2021).
131+
See `Contributor guide <https://pysindy.readthedocs.io/en/latest/contributing.html>`_
263132

264133
Reporting issues or bugs
265134
^^^^^^^^^^^^^^^^^^^^^^^^

‎docs/contributing.rst‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
2+
3+
Contributing to pysindy
4+
================================
5+
We welcome all sorts of contributions!
6+
There are generally three different types of contributions.
7+
Please be aware of how to conduct yourself in an online, professional environment;
8+
We have a contributor `code of conduct`_.
9+
10+
.. _code of conduct: https://github.com/dynamicslab/pysindy/docs/contributor_covenant.md
11+
12+
13+
14+
Three types of contributions
15+
--------------------------------
16+
The pysindy repository combines several different types of users and use cases:
17+
18+
* You want to discover an ODE for your particular data, potentially as a research paper
19+
* You want to publish a new methods of learning differential equations from data,
20+
making it available to other users
21+
* You are learning about equation discovery from reading papers, and this repo is
22+
an educational supplement to existing papers/textbooks.
23+
24+
There are several different ways people contribute:
25+
26+
* Sharing a novel use case/research notebook with the wider public
27+
* Adding features or fixing bugs
28+
* Improving documentation.
29+
30+
Contributing examples
31+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
32+
We love seeing examples of PySINDy being used to solve interesting problems!
33+
If you would like to contribute an example to the documentation,
34+
reach out to us by creating an issue.
35+
36+
Examples are external repositories that
37+
`follow a structure <https://github.com/dynamicslab/pysindy-example>`_.
38+
They tend to be pinned to a set of dependencies and may not be kept up to date
39+
with breaking API changes.
40+
Pysindy has a sphinx extension that allows incorporating externally-built docs,
41+
so long as it follows that structure.
42+
Once your example repository is fully built, create a PR here that adds your repo
43+
to examples/external.yml and examples/README.rst as:
44+
45+
46+
.. code-block:: rst
47+
:caption: examples/README.rst
48+
49+
.. pysindy-example::
50+
:key: your-example-key
51+
:title: Title of your example
52+
53+
A description of your example
54+
55+
.. code-block:: yaml
56+
:caption: external.yml
57+
58+
- name: "your-example-key"
59+
user: "user-or-org-owning-repo"
60+
repo: "repo-name"
61+
ref: "git hash of commit"
62+
dir: "name of folder with examples in it, e.g. 'examples' or '.'"
63+
64+
65+
.. hint::
66+
67+
The most frequent issue in linking external documentation is header levels.
68+
The sphinx directive adjusts section levels to fit correctly within our
69+
documentation.
70+
This means that notebooks need to have exactly one highest-level header as
71+
the document link text.
72+
Subordinate levels should proceed in a rational way, e.g. level two headers
73+
following level one headers, etc.
74+
75+
If you want to keep your example up to date with pysindy main branch,
76+
i.e. across breaking changes, that is also possible.
77+
*This repository* has the CI job ``notify-experiments`` that sends a
78+
repository-dispatch action to repos that want to be notfied of changes to pysindy.
79+
The example repository has a CI job (``pysindy.yml``) that can be cued by such dispatch.
80+
You will have to add your repository information to the ``notify-experiments``
81+
and add a `fine-grained PAT <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens>`_
82+
with permissions ``contents: read & write`` and ``metadata: read only``,
83+
then record that in pysindy's github secrets.
84+
Alternatively, you could trigger your builds based upon cron timing.
85+
86+
Updates to an example are not automitcally used in the pysindy doc build.
87+
To update an example, you need to change the commit information
88+
in ``examples/external.yml``.
89+
90+
Contritubing documentation
91+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
92+
93+
We of course love documentation improvements!
94+
Begin by opening an issue;
95+
sometimes the problem is that the documentation is correct, but the code has a bug.
96+
Other times, the documentation is merely out of date.
97+
We attempt to follow the `divio format`_ of
98+
tutorials, how-to, reference, and explanation.
99+
We also have a section for research paper examples as a very specific form of how-to.
100+
101+
When making a documentation PR, it helps to pass CI if you build the check that the
102+
documentation builds locally first.
103+
See `Building docs`_
104+
105+
106+
.. _divio format: https://docs.divio.com/documentation-system/
107+
108+
Contributing code
109+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
110+
Similar to other open-source projects, most contributions start with a github issue
111+
in order to solicit concurrence from project maintainers.
112+
Then, the general process is:
113+
1. Fork the repository
114+
1. Step through the `Set up development environment`_.
115+
1. Hack Hack Hack according to `Coding Guidelines`_.
116+
1. Open a pull request
117+
1. Respond to reviews
118+
119+
A good place to get started learning this process is to follow one of the issues labeled
120+
`good first issue`_.
121+
122+
.. _good first issue: https://github.com/dynamicslab/pysindy/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22
123+
124+
Development process
125+
--------------------------------
126+
127+
Set up development environment
128+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
129+
Clone the repo, then create a project isolation in your environment manager of choice
130+
(e.g. venv, conda, virtualenv).
131+
Install the project in an editable way with all optional dependencies, e.g.
132+
133+
.. code-block:: bash
134+
135+
pip install -e .[dev,miosr,cvxpy,docs,sbr]
136+
137+
This will allow you to run unit tests and automatically format your code.
138+
To be accepted your code should conform to PEP8 and pass all unit tests.
139+
Code can be tested by invoking
140+
141+
.. code-block:: bash
142+
143+
pytest
144+
145+
We recommend using ``pre-commit`` to format your code. The easiest approach is to install pre-commit via
146+
147+
.. code-block:: bash
148+
149+
pre-commit install
150+
151+
After which pre-commit will automatically check all future commits.
152+
153+
154+
155+
Coding Guidelines
156+
^^^^^^^^^^^^^^^^^^^^
157+
158+
Hack away, following PEP 484, PEP 8, and other relevant guidelines.
159+
Automated tooling (``pre-commit``) will hopefully keep you on track here.
160+
161+
Stage your changes with:
162+
163+
.. code-block:: bash
164+
165+
git add path/to/changed/file.py
166+
167+
Pre-commit will then automatically run all checks against your committed code. If you want to trigger this manually, you can run the following to automatically reformat your staged code
168+
169+
.. code-block:: bash
170+
171+
pre-commit
172+
173+
Note that you will then need to re-stage any changes ``pre-commit`` made to your code.
174+
175+
Make sure to write useful commit messages.
176+
Consider that developers years from now will use ``git log -S`` and ``git blame``
177+
to discover when certain changes took place and unearth why you made
178+
the choices you did.
179+
180+
For good guidance on commit messages, see `what makes a good git commit`_ or
181+
`conventional commits`_. TL;DR: Subjects in imperative tense, less than 72 characters.
182+
If necessary, body describes why the change was made, e.g. previous behavior,
183+
spooky action at a distance. If the commit resolves
184+
a github issue, use github's automatic issue-\ `closing words`_.
185+
Lines in the commit body should not exceed 80 characters.
186+
187+
.. _conventional commits: https://www.conventionalcommits.org/en/v1.0.0/
188+
.. _what makes a good git commit: https://www.simplethread.com/what-makes-a-good-git-commit/
189+
.. _closing words: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword
190+
191+
Building docs
192+
^^^^^^^^^^^^^^^^^^
193+
With all optional dependencies installed, run:
194+
195+
.. code-block:: bash
196+
197+
python -m sphinx -TEWb html -d _build/doctrees -D language=en docs docs/_build
198+
199+
Or check the build step in the most recent CI run or [RTD build](https://readthedocs.org/projects/pysindy/builds/).
200+
201+
Desired changes
202+
-----------------------
203+
204+
There are a number of SINDy variants and advanced functionality that would be great to implement in future releases:
205+
206+
1. Bayesian SINDy, for instance that from Hirsh, Seth M., David A. Barajas-Solano, and J. Nathan Kutz. "Sparsifying Priors for Bayesian Uncertainty Quantification in Model Discovery." arXiv preprint arXiv:2107.02107 (2021).
207+
208+
2. Tensor SINDy, using the methods in Gelß, Patrick, et al. "Multidimensional approximation of nonlinear dynamical systems." Journal of Computational and Nonlinear Dynamics 14.6 (2019).
209+
210+
3. Stochastic SINDy, using the methods in Brückner, David B., Pierre Ronceray, and Chase P. Broedersz. "Inferring the dynamics of underdamped stochastic systems." Physical review letters 125.5 (2020): 058103.
211+
212+
4. Integration of PySINDy with a Python model-predictive control (MPC) code.
213+
214+
5. The PySINDy weak formulation is based on the work in Reinbold, Patrick AK, Daniel R. Gurevich, and Roman O. Grigoriev. "Using noisy or incomplete data to discover models of spatiotemporal dynamics." Physical Review E 101.1 (2020): 010203. It might be useful to additionally implement the weak formulation from Messenger, Daniel A., and David M. Bortz. "Weak SINDy for partial differential equations." Journal of Computational Physics (2021): 110525. The weak formulation in PySINDy is also fairly slow and computationally intensive, so finding ways to speed up the code would be great.
215+
216+
6. The blended conditional gradients (BCG) algorithm for solving the constrained LASSO problem, Carderera, Alejandro, et al. "CINDy: Conditional gradient-based Identification of Non-linear Dynamics--Noise-robust recovery." arXiv preprint arXiv:2101.02630 (2021).

‎docs/contributor_covenant.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ representative at an online or offline event.
6161

6262
Instances of abusive, harassing, or otherwise unacceptable behavior may be
6363
reported to the community leaders responsible for enforcement at
64-
[email protected] or briandesilva1@gmail.com.
64+
[email protected] or jacob.stevens.haas@gmail.com.
6565
All complaints will be reviewed and investigated promptly and fairly.
6666

6767
All community leaders are obligated to respect the privacy and security of the

0 commit comments

Comments
 (0)