Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
65 lines (41 loc) · 3.15 KB

CONTRIBUTING.md

File metadata and controls

65 lines (41 loc) · 3.15 KB
Raw

Contributing to micro_deer

Thanks for your interest in contributing! micro_deer is meant to be a gentle, inviting introduction to parallelizing nonlinear state space models. Contributions of all sizes are welcome — from typo fixes to new example systems.

Project philosophy

This is educational code. Clarity and simplicity are prioritized over performance and generality. When contributing, please:

  • Prefer readable code over clever code.
  • Keep changes minimal and focused — avoid speculative generality or configurability.
  • If a change would make the code faster but harder to read, it probably doesn't belong here.

Ways to contribute

  • Bug reports and questions — open a GitHub issue.
  • Bug fixes and small improvements — open a pull request.
  • New example dynamical systems or notebooks — great way to showcase the solvers on new problems.
  • Bibliography additions — the README's annotated bibliography aims to be comprehensive; let us know what we've missed!

Development setup

Requires Python >= 3.10 and uv.

git clone https://github.com/lindermanlab/micro_deer.git
cd micro_deer
uv sync --extra dev

Optional hardware backends: --extra metal (macOS ARM) or --extra cuda (Linux).

Running tests

uv run --extra dev python -m pytest test/ -v

Please make sure all tests pass before opening a pull request. If you change solver code or add a new solver, add tests to test/test_micro_deer.py — the existing style is plain test_* pytest functions that validate parallel solvers against a sequential jax.lax.scan ground truth.

Pull request workflow

  1. Fork the repo and create a branch from main.
  2. Make your changes (with tests, if applicable).
  3. Open a pull request against main describing what you changed and why.

Small, focused PRs are easier to review and more likely to be merged quickly.

Code conventions

  • New dynamical systems should subclass DynamicalSystem (an equinox.Module, in src/micro_deer/dynamical_systems/dynamics.py) and implement deer_fxn(state, input) and scan_fxn(state, input). All state-space models use the signature f(state, input) -> next_state.
  • Functions passed to the solvers must be JAX-traceable (compatible with vmap, jacfwd, lax.scan, lax.associative_scan).
  • Use package-relative imports, e.g. from micro_deer.dynamical_systems.dynamics import DynamicalSystem.
  • There's no enforced formatter or linter — just match the style of the surrounding code.

Bibliography contributions

References added to the README's annotated bibliography must be real, verified papers: please double-check the title, author list, and link before submitting. A one- or two-sentence annotation explaining the paper's contribution is appreciated.

Conduct

Be kind, respectful, and constructive. This is a small research project maintained by the Linderman Lab — we want it to be a welcoming place to learn.

License

By contributing, you agree that your contributions will be licensed under the MIT License that covers this project.