Contributing to vibe-qc

Contributions are welcome. This page is the short version; ask on the issue tracker if something below is unclear.

For security-relevant reports (vulnerabilities, crashes with a chance of being exploitable), see SECURITY.md instead — do not open a public issue.

All contributors and maintainers are expected to follow the Code of Conduct.

Before you open a merge request

  1. Confirm no existing issue already covers the change — if there is one, comment on it so we can coordinate.

  2. Run the test suite locally and confirm it passes:

    .venv/bin/python -m pytest tests/

  3. If your change touches documentation, build the Sphinx docs locally and skim the affected pages:

    sphinx-build -b html docs/ docs/_build/html

  4. For anything that adds a dependency or changes public API, open an issue first to check scope fit.

Code style

  • C++17. Four-space indent, brace on same line for control flow. Everything in cpp/ lives under namespace vibeqc { ... }. Match the patterns in cpp/src/rhf.cpp / cpp/src/integrals.cpp.

  • Python 3.11+. PEP 8 with four-space indent. Start every module with from __future__ import annotations. Type hints on public API; local helpers can skip them.

  • Prefer editing existing modules over introducing new ones. If a new file is the right choice, follow the neighbours’ layout.

Commit messages

  • Imperative mood, first line under 72 characters (e.g. Fix SCF divergence on CH3 with SAD guess).

  • Longer rationale in the body if the what doesn’t explain itself.

  • Co-author trailers are fine for pair work.

What we won’t accept (for now)

  • API changes that break public signatures without a deprecation path.

  • New hard dependencies added without prior discussion — open an issue first.

  • Changes that regress the test suite without a stated rationale and a plan to restore.

Licensing

By submitting a patch, pull request, or any other contribution to vibe-qc, you agree that:

  1. Your contribution is licensed under the Mozilla Public License 2.0 (the project licence — see LICENSE).

  2. You grant the project owner (Michael F. Peintinger) the right to relicense your contribution under alternative terms, including a future commercial licence, alongside the MPL 2.0 public licence. You retain copyright.

This is a lightweight alternative to a formal Contributor License Agreement. If you’re not comfortable with (2), please open an issue before contributing so we can discuss.

vibe-qc’s compiled core links libint (MPL 2.0), libxc (MPL 2.0), Eigen (MPL 2.0 / BSD-3), spglib (BSD-3), and pybind11 (BSD-3) — all MPL-compatible.