Merge pull request #45 from caltechmsc/docs/44-implement-comprehensive-project-documentation

docs(project): Implement Comprehensive User, API, and Developer Documentation

Author: TKanX

.github/workflows/release.yml

@@ -69,7 +69,7 @@ jobs:
           SOURCE_PATH="target/${{ matrix.target }}/release/$BINARY_NAME"
 
           cp "$SOURCE_PATH" "$ARTIFACT_DIR/$BINARY_NAME"
-          cp LICENSE README.md "$ARTIFACT_DIR/"
+          cp LICENSE README.md docs/cli/USAGE.md docs/cli/config.template.toml "$ARTIFACT_DIR/"
 
           cd $ARTIFACT_DIR
 

README.md

@@ -12,16 +12,120 @@ The core mission of SCREAM++ is to provide a robust, reliable, and easy-to-use t
 - **Flexible Optimization Modes**: Supports both global side-chain optimization and focused refinement within a defined **binding site** or region of interest.
 - **Modern Tooling**: Managed by Cargo for simple, reproducible builds and dependency management.
 - **Multiple Interfaces**:
-  - **Standalone CLI**: An easy-to-use command-line interface for standard prediction tasks.
-  - **Python Package**: A user-friendly Python API (via PyO3) for scripting, integration, and advanced workflows.
-  - **C-Compatible Library**: A C FFI layer for integration with C, C++, and other programming languages.
-  - **Native Rust Crate**: A core Rust library (`screampp`) available on crates.io for direct use in other Rust-based scientific computing projects.
+  - **Standalone CLI**: A powerful and easy-to-use command-line interface for all prediction tasks.
+  - **Native Rust Crate**: The core library (`screampp`) is available on [crates.io](https://crates.io/crates/screampp) for direct use in other Rust-based scientific computing projects.
+  - **Python Package (Future)**: A user-friendly Python API (via PyO3) for scripting and integration is planned for future releases.
+  - **C-Compatible Library (Future)**: A C FFI layer for integration with C, C++, and other languages is planned for future releases.
+
+## Getting Started
+
+There are two main ways to use SCREAM++: as a standalone command-line tool or as a library in your own Rust project.
+
+### 1. Using the Command-Line Interface (CLI)
+
+This is the recommended method for most users.
+
+#### Step 1: Download the executable
+
+Go to the [**GitHub Releases page**](https://github.com/caltechmsc/screampp/releases) and download the pre-compiled binary for your operating system (Linux, macOS, Windows). Unzip the archive.
+
+#### Step 2: Download the required data files
+
+The first time you run the CLI, you must download the necessary forcefield and rotamer library files. This is a one-time setup.
+
+```bash
+# On Linux/macOS
+./scream data download
+
+# On Windows (Command Prompt)
+scream.exe data download
+```
+
+This command will fetch and unpack the data to a default location on your system.
+
+#### Step 3: Run a prediction
+
+You are now ready to run a side-chain placement job.
+
+```bash
+# Optimize all side-chains in input.bgf and save the result
+./scream place -i path/to/input.bgf -o path/to/output.bgf
+```
+
+For detailed instructions on all commands, options, and advanced configuration, please refer to the [**CLI User Manual**](docs/cli/USAGE.md).
+
+### 2. Using as a Rust Library
+
+If you are a Rust developer, you can add `screampp` as a dependency to your project.
+
+#### Step 1: Add to `Cargo.toml`
+
+```toml
+[dependencies]
+screampp = "0.5.0"
+```
+
+#### Step 2: Use in your code
+
+You can now use the high-level `workflows` API to perform side-chain placement programmatically.
+
+```rust
+use screampp::core::io::bgf::BgfFile;
+use screampp::engine::config::{PlacementConfigBuilder, ResidueSelection, ConvergenceConfig};
+use screampp::engine::progress::ProgressReporter;
+use screampp::workflows::place;
+
+fn run_placement() -> Result<(), Box<dyn std::error::Error>> {
+    let (system, metadata) = BgfFile::read_from_path("path/to/input.bgf")?;
+
+    let config = PlacementConfigBuilder::new()
+        .forcefield_path("path/to/data/forcefield/dreiding-lj-12-6-0.4.toml")
+        .delta_params_path("path/to/data/delta/delta-rmsd-1.0.csv")
+        .s_factor(1.1)
+        .rotamer_library_path("path/to/data/rotamers/charmm@rmsd-1.0.toml")
+        .topology_registry_path("path/to/data/topology/registry.toml")
+        .residues_to_optimize(ResidueSelection::All)
+        .max_iterations(100)
+        .num_solutions(1)
+        .include_input_conformation(true)
+        .final_refinement_iterations(2)
+        .convergence_config(ConvergenceConfig {
+            energy_threshold: 0.01,
+            patience_iterations: 5,
+        })
+        .build()?;
+
+    let reporter = ProgressReporter::new(); // Or provide a callback for progress updates
+    let result = place::run(&system, &config, &reporter)?;
+
+    if let Some(best_solution) = result.solutions.first() {
+        println!("Best energy: {:.2} kcal/mol", best_solution.total_energy);
+    }
+
+    Ok(())
+}
+```
+
+## Documentation
+
+Comprehensive documentation is available for both users and developers.
+
+- **For Users**:
+
+  - [**CLI User Manual**](docs/cli/USAGE.md): A complete guide to installing and using the `scream` command-line tool, including detailed explanations of all commands, configuration options, and practical examples.
+
+- **For Developers**:
+
+  - [**Rust Library API Docs (docs.rs)**](https://docs.rs/screampp): The official, versioned API documentation for the `scream-core` (`screampp`) crate, generated by `rustdoc`. This is the best resource for understanding the public API of the library.
+  - **Developer Documentation**: In-depth documentation covering the architecture, data models, algorithms, and design philosophy of the entire project. This is essential reading for anyone looking to contribute to or deeply understand the internals of SCREAM++.
+    - [**`scream-core` Developer Docs**](docs/dev/core/README.md): Details the internal architecture, data models, and algorithms of the `scream-core` library.
+    - [**`scream-cli` Developer Docs**](docs/dev/cli/README.md): Provides a comprehensive technical breakdown of the `scream-cli` crate, including execution flow, configuration handling, and data management.
 
 ## Tech Stack
 
-- **Language**: Rust
-- **Supported Languages**: Rust, Python (via PyO3), C/C++ (via FFI)
+- **Core Language**: Rust
 - **Build System**: Cargo
+- **Planned Interfaces**: Python (via PyO3), C/C++ (via FFI)
 
 ## License
 

crates/scream-core/src/core/forcefield/energy.rs

@@ -4,20 +4,59 @@ use crate::core::models::ids::ResidueId;
 use std::f64::consts::PI;
 use thiserror::Error;
 
+/// Represents errors that can occur during energy calculations in the force field.
+///
+/// This enum encapsulates various error conditions that may arise when computing
+/// interaction energies between atoms, providing detailed context for debugging
+/// and error handling in molecular simulations.
 #[derive(Debug, Error)]
 pub enum EnergyCalculationError {
+    /// Indicates that an atom lacks the necessary parameters for van der Waals energy calculation.
+    ///
+    /// This error occurs when attempting to compute VDW interactions for atoms that have
+    /// not been parameterized with appropriate force field parameters (e.g., Lennard-Jones
+    /// or Buckingham parameters).
     #[error(
         "Atom '{atom_name}' in residue {residue_id:?} is not parameterized for VDW calculation"
     )]
     UnparameterizedAtom {
+        /// The name of the atom that is missing parameters.
         atom_name: String,
+        /// The ID of the residue containing the unparameterized atom.
         residue_id: ResidueId,
     },
 }
 
+/// Provides static methods for calculating various types of molecular interaction energies.
+///
+/// This struct serves as a utility for computing energy contributions from different
+/// force field terms, including van der Waals, electrostatic, and hydrogen bonding
+/// interactions. All methods are designed to work with the SCREAM++ molecular
+/// data structures and follow standard force field conventions.
 pub struct EnergyCalculator;
 
 impl EnergyCalculator {
+    /// Calculates the van der Waals interaction energy between two atoms.
+    ///
+    /// This method computes the VDW energy using either Lennard-Jones 12-6 or Buckingham
+    /// exponential-6 potentials, depending on the parameterization of the atoms. It combines
+    /// parameters from both atoms using standard mixing rules and applies a flat-bottom
+    /// modification based on the atoms' delta values to handle close contacts.
+    ///
+    /// # Arguments
+    ///
+    /// * `atom1` - The first atom participating in the interaction
+    /// * `atom2` - The second atom participating in the interaction
+    ///
+    /// # Return
+    ///
+    /// Returns the calculated VDW energy in kcal/mol. Positive values indicate repulsive
+    /// interactions, negative values indicate attractive interactions.
+    ///
+    /// # Errors
+    ///
+    /// Returns `EnergyCalculationError::UnparameterizedAtom` if either atom lacks
+    /// VDW parameters.
     pub fn calculate_vdw(atom1: &Atom, atom2: &Atom) -> Result<f64, EnergyCalculationError> {
         let extract_params = |atom: &Atom| match atom.vdw_param {
             CachedVdwParam::LennardJones { radius, well_depth } => Ok((radius, well_depth, 0.0)),
@@ -37,6 +76,7 @@ impl EnergyCalculator {
 
         let dist = (atom1.position - atom2.position).norm();
 
+        // Combine delta values to determine the flat-bottom cutoff distance
         let total_delta = (atom1.delta.powi(2) + atom2.delta.powi(2)).sqrt();
         let r_min_combined = (r_min1 + r_min2) / 2.0;
         let well_depth_combined = (well_depth1 * well_depth2).sqrt();
@@ -54,11 +94,46 @@ impl EnergyCalculator {
         Ok(energy)
     }
 
+    /// Calculates the electrostatic Coulomb interaction energy between two atoms.
+    ///
+    /// This method computes the electrostatic energy using Coulomb's law with a distance-
+    /// dependent dielectric constant. The calculation assumes point charges and does not
+    /// include any cutoff or screening effects beyond the dielectric.
+    ///
+    /// # Arguments
+    ///
+    /// * `atom1` - The first atom participating in the interaction
+    /// * `atom2` - The second atom participating in the interaction
+    /// * `dielectric` - The dielectric constant of the medium (dimensionless)
+    ///
+    /// # Return
+    ///
+    /// Returns the calculated Coulomb energy in kcal/mol. The sign depends on the
+    /// charges: positive for like charges, negative for opposite charges.
     pub fn calculate_coulomb(atom1: &Atom, atom2: &Atom, dielectric: f64) -> f64 {
         let dist = (atom1.position - atom2.position).norm();
         potentials::coulomb(dist, atom1.partial_charge, atom2.partial_charge, dielectric)
     }
 
+    /// Calculates the hydrogen bonding interaction energy between donor, hydrogen, and acceptor atoms.
+    ///
+    /// This method implements the Dreiding hydrogen bond potential with a 12-10 distance
+    /// dependence and an angular term based on the donor-hydrogen-acceptor angle. The
+    /// potential is zero for angles ≤ 90° and includes a flat-bottom modification for
+    /// close contacts based on the atoms' delta values.
+    ///
+    /// # Arguments
+    ///
+    /// * `donor` - The donor atom in the hydrogen bond
+    /// * `hydrogen` - The hydrogen atom attached to the donor
+    /// * `acceptor` - The acceptor atom in the hydrogen bond
+    /// * `r_hb` - The equilibrium hydrogen bond distance in Å
+    /// * `d_hb` - The well depth of the hydrogen bond potential in kcal/mol
+    ///
+    /// # Return
+    ///
+    /// Returns the calculated hydrogen bond energy in kcal/mol. Negative values indicate
+    /// favorable hydrogen bonding interactions.
     pub fn calculate_hbond(
         donor: &Atom,
         hydrogen: &Atom,
@@ -71,10 +146,12 @@ impl EnergyCalculator {
         let v_hd = donor.position - hydrogen.position;
         let angle_ahd_deg = v_ha.angle(&v_hd).to_degrees();
 
+        // Hydrogen bonds are only considered for angles > 90°
         if angle_ahd_deg <= 90.0 {
             return 0.0;
         }
 
+        // Combine delta values for flat-bottom cutoff
         let total_delta = (acceptor.delta.powi(2) + donor.delta.powi(2)).sqrt();
         let distance_potential_fn =
             |d: f64| -> f64 { potentials::dreiding_hbond_12_10(d, r_hb, d_hb) };

crates/scream-core/src/core/forcefield/mod.rs

@@ -1,6 +1,43 @@
-pub mod energy;
+//! # Force Field Module
+//!
+//! This module provides the core functionality for molecular mechanics force field calculations
+//! in the SCREAM++ protein side-chain placement library. It implements energy evaluation,
+//! parameter management, and scoring algorithms for molecular interactions.
+//!
+//! ## Overview
+//!
+//! The force field module is responsible for computing interaction energies between atoms
+//! and molecular groups using classical molecular mechanics potentials. It supports:
+//!
+//! - **Van der Waals interactions** using Lennard-Jones and Buckingham potentials
+//! - **Electrostatic interactions** with Coulomb's law and distance-dependent dielectric
+//! - **Hydrogen bonding** using specialized 12-10 potentials
+//! - **Energy weighting** based on atom roles (backbone vs sidechain)
+//! - **Parameter management** for different force field types and atom types
+//!
+//! ## Key Components
+//!
+//! - [`params`] - Force field parameter structures and configuration
+//! - [`scoring`] - High-level energy scoring interface for molecular systems
+//! - [`term`] - Energy term aggregation and reporting
+//! - [`parameterization`] - Automatic assignment of force field parameters to atoms
+//!
+//! ## Usage
+//!
+//! The main entry point for energy calculations is the [`scoring::Scorer`] struct,
+//! which provides methods to compute interaction energies between atom groups while
+//! properly handling bonded exclusions and energy weighting.
+//!
+//! ```ignore
+//! use screampp::core::forcefield::scoring::Scorer;
+//!
+//! let scorer = Scorer::new(&system, &forcefield);
+//! let energy = scorer.score_interaction(query_atoms, environment_atoms)?;
+//! ```
+
+pub(crate) mod energy;
 pub mod parameterization;
 pub mod params;
-pub mod potentials;
+pub(crate) mod potentials;
 pub mod scoring;
 pub mod term;