Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,32 @@

## Project Structure & Module Organization

RustiQ is a Rust 2021 Cargo binary crate. The executable entry point is `src/main.rs`, with CLI wiring in `src/cli/` using `clap`. Domain modules live under `src/basis/`, `src/molecules/`, `src/hf/`, `src/runfile/`, `src/math_utils.rs`, and `src/eri.rs`. Unit tests are colocated in `#[cfg(test)] mod tests` blocks next to the code they exercise. Shared test helpers are in `src/test_utils.rs`. Example inputs are in `samples/`, and fixture data is in `tests/data/`.
RustiQ is a Rust 2021 Cargo workspace with two crates. The root `RustiQ` package is the CLI binary: `src/main.rs` is its entry point, `src/cli/` handles commands and reports, and `src/runfile/` parses TOML, reports input errors, and converts runfile options to scientific configuration. The reusable `rustiq-core` library lives in `crates/rustiq-core/`; its `src/config/` and `src/calculation/` modules define and run calculations, while `src/molecules/`, `src/basis/`, `src/eri/`, `src/hf/`, and `src/mp2/` contain the scientific implementation. Keep runfile parsing and terminal presentation in the CLI crate. Example inputs are in `samples/`, CLI fixtures are in `tests/data/`, and core fixtures are in `crates/rustiq-core/tests/data/`.

## Build, Test, and Development Commands

- `cargo build`: compile the project in debug mode.
- `cargo run -- run samples/calculation.toml`: run a sample calculation file through the CLI.
- `cargo test`: run the full unit test suite.
- `cargo fmt`: format Rust code with `rustfmt`.
- `cargo clippy --all-targets --all-features`: run lints across the crate before submitting larger changes.
- `cargo build --workspace`: compile both crates in debug mode.
- `cargo run -- run samples/h2/sto-3g/calculation.toml`: run a sample calculation through the CLI.
- `cargo fmt --all -- --check`: check Rust formatting without changing files.
- `cargo clippy --workspace --all-targets --all-features -- -D warnings`: run the CI lint check.
- `cargo test --workspace --all-targets --all-features`: run tests with all features enabled.
- `cargo test --workspace --all-targets --no-default-features`: check the offline configuration.

Keep `Cargo.lock` committed because this repository builds an application, not a reusable library.
Keep `Cargo.lock` committed because the workspace includes an application. The CLI enables the `online` feature by default; `rustiq-core` has no default features and can be checked independently with `cargo test -p rustiq-core --no-default-features`.

## Coding Style & Naming Conventions

Follow standard Rust formatting: four-space indentation, `snake_case` for functions, modules, and variables, `PascalCase` for types and enum variants, and `SCREAMING_SNAKE_CASE` for constants. Prefer small modules that mirror the current directory structure, for example `src/basis/gaussian/shell.rs` for Gaussian shell behavior. Use typed errors such as `thiserror` where appropriate instead of stringly typed failures. Keep comments focused on non-obvious math, chemistry assumptions, or CLI behavior.
Follow standard Rust formatting: four-space indentation, `snake_case` for functions, modules, and variables, `PascalCase` for types and enum variants, and `SCREAMING_SNAKE_CASE` for constants. Prefer small modules that mirror the current directory structure, for example `crates/rustiq-core/src/basis/gaussian/shell.rs` for Gaussian shell behavior. Use typed errors such as `thiserror` where appropriate instead of stringly typed failures. Keep comments focused on non-obvious math, chemistry assumptions, or CLI behavior.

## Testing Guidelines

Use Rust’s built-in test framework. Place focused unit tests in the same file as the implementation, following the existing `mod tests` pattern. Name tests by the behavior being checked, such as `test_distance_matrix` or `test_boys_function_zero`. Put reusable fixtures in `tests/data/` and small sample run configurations in `samples/`. Run `cargo test` before opening a pull request; add tests when changing numerical routines, parsers, basis-set handling, or SCF behavior.
Use Rust's built-in test framework. Place focused unit tests beside the implementation in `#[cfg(test)] mod tests` blocks; shared core test helpers are in `crates/rustiq-core/src/test_utils.rs`. Integration tests for the CLI are in root `tests/`, and core API tests are in `crates/rustiq-core/tests/`. Put reusable fixtures in the corresponding crate's `tests/data/` directory and small run configurations in `samples/`. The CLI's versioned JSON output schema is in `schemas/calculation-output-v1.schema.json` and is checked by `tests/json_output_cli.rs`. For changes to integrals, SCF, MP2, basis handling, or geometry parsing, add focused tests and compare numerical results with an established package when possible; explain affected energies and tolerance changes. PySCF reference comparisons live in `tools/reference/` and run separately from Cargo tests with `uv run --locked pytest tools/reference`.

## Commit & Pull Request Guidelines

Name every task branch using the `type/name` format, with a lowercase type and a lowercase, hyphen-separated English description. Choose a type that describes the work, such as `feature/*`, `fix/*`, `chore/*`, `docs/*`, `test/*`, `refactor/*`, `perf/*`, or `ci/*`. These are examples, not an exhaustive list; other appropriate types are allowed. For example: `feature/add-xyz-parser`, `fix/scf-convergence`, or `chore/add-mp2-pyscf-reference-cases`. Do not create task branches without a type prefix.

The current history only contains an initial commit, so use clear, imperative commit messages going forward, for example `Add XYZ geometry parser` or `Fix SCF convergence threshold`. Pull requests should include a short summary, the commands used for verification, and any relevant input files or numerical output changes. Link related issues when available. For CLI or output formatting changes, include before/after snippets rather than screenshots unless terminal rendering is visually important.
Use clear, imperative commit messages, for example `Add XYZ geometry parser` or `Fix SCF convergence threshold`. Pull requests should include a short summary, the commands used for verification, and any relevant input files or numerical output changes. Link related issues when available. For CLI or output formatting changes, include before/after snippets rather than screenshots unless terminal rendering is visually important.

## Agent-Specific Instructions

Expand Down