CONTRIBUTING.md

Contributing to Atoms_Rust

Thank you for your interest in contributing! This document provides guidelines for contributing to the project.

---

Table of Contents

1. Code of Conduct
2. Development Setup
3. Code Style
4. Pull Request Process
5. Adding New Features
6. Testing
7. Documentation

---

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Help others learn and grow

---

Development Setup

Prerequisites

• Rust 1.70 or later
• Platform-specific dependencies (see GETTING_STARTED.md)

Initial Setup

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/Atoms.git
cd Atoms/Atoms_Rust

# Build the project
cargo build

# Run tests
cargo test

# Run a binary to verify setup
cargo run --bin realtime

Recommended Tools

# Install rustfmt and clippy
rustup component add rustfmt clippy

# Run formatting check
cargo fmt --check

# Run linter
cargo clippy --all-targets --all-features

---

Code Style

Formatting

We use rustfmt with default settings. Before committing:

cargo fmt

Linting

We use clippy for additional linting. Address all warnings:

cargo clippy --all-targets --all-features -- -D warnings

Naming Conventions

Item	Convention	Example
Types	PascalCase	OrbitCamera, Sampler
Functions	snake_case	sample_phi, calculate_probability_flow
Constants	SCREAMING_SNAKE_CASE	ELECTRON_R, A0
Modules	snake_case	physics, render

Documentation

All public items must have documentation comments:

/// Calculate probability current at a position.
///
/// For states with m ≠ 0, returns the velocity of probability flow.
/// This gives the circulating motion visible in orbitals like 2p±1.
///
/// # Arguments
///
/// * `pos` - Position in Cartesian coordinates
/// * `n` - Principal quantum number
/// * `l` - Angular momentum quantum number
/// * `m` - Magnetic quantum number
///
/// # Returns
///
/// Velocity vector representing probability current flow.
///
/// # Example
///
/// ```
/// use atoms_rust::calculate_probability_flow;
/// use macroquad::prelude::Vec3;
///
/// let vel = calculate_probability_flow(Vec3::new(5.0, 0.0, 5.0), 2, 1, 1);
/// ```
pub fn calculate_probability_flow(pos: Vec3, n: i32, l: i32, m: i32) -> Vec3 {
    // Implementation...
}

Error Handling

Use Result for fallible operations. Use thiserror for custom error types:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum PhysicsError {
    #[error("Invalid quantum numbers: n={n}, l={l}, m={m}")]
    InvalidQuantumNumbers { n: i32, l: i32, m: i32 },

    #[error("CDF table not built for n={n}, l={l}")]
    CdfNotBuilt { n: i32, l: i32 },
}

---

Pull Request Process

Before Submitting

1. Create an issue describing the bug or feature
2. Fork the repository and create a feature branch
3. Make your changes following code style guidelines
4. Add tests for new functionality
5. Update documentation as needed
6. Run all checks:

   cargo fmt --check
   cargo clippy --all-targets --all-features -- -D warnings
   cargo test
   cargo doc --no-deps

PR Title Format

Use conventional commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• refactor: - Code refactoring
• test: - Adding tests
• chore: - Maintenance tasks

Examples:

• feat: add 4f orbital presets
• fix: correct Laguerre polynomial recurrence
• docs: add installation guide for Windows

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring

## Testing
Describe how you tested these changes

## Checklist
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All checks pass

Review Process

1. PRs require at least one approval
2. Address all review comments
3. Squash commits before merge (if requested)

---

Adding New Features

Adding a New Orbital Preset

1. Add preset definition in appropriate binary
2. Update documentation with new preset
3. Add example to user guide

Adding a New Visualization Mode

1. Create new binary in src/bin/
2. Import library functions:

   use atoms_rust::{
       inferno, sample_phi, spherical_to_cartesian,
       OrbitCamera, Sampler,
   };

3. Add to Cargo.toml:

   [[bin]]
   name = "your_visualizer"
   path = "src/bin/your_visualizer.rs"

4. Add documentation in user guide

Adding New Physics Functions

1. Add function to appropriate module in src/physics/
2. Export from mod.rs
3. Add to lib.rs re-exports
4. Write unit tests
5. Document with rustdoc and LaTeX formulas

---

Testing

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_laguerre_base_cases() {
        assert!((laguerre(1, 0, 1.0) - 1.0).abs() < 1e-10);
        assert!((laguerre(2, 0, 1.0) - 1.0).abs() < 1e-10);
    }

    #[test]
    fn test_spherical_to_cartesian() {
        let pos = spherical_to_cartesian(1.0, std::f32::consts::FRAC_PI_2, 0.0);
        assert!((pos.x - 1.0).abs() < 1e-6);
        assert!(pos.y.abs() < 1e-6);
        assert!(pos.z.abs() < 1e-6);
    }
}

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_laguerre

# Run with output
cargo test -- --nocapture

Benchmarking

# Run benchmarks
cargo bench

---

Documentation

Building Documentation

cargo doc --open

Documentation Files

When adding features, update relevant docs:

Change	Update
New binary	README.md, USER_GUIDE.md
New physics	PHYSICS.md, API_REFERENCE.md
Architecture change	ARCHITECTURE.md
Performance change	PERFORMANCE.md

---

Getting Help

• Open an issue for questions
• Check existing issues before opening new ones
• Join discussions on existing issues

Thank you for contributing! 🎉