Description:

The library's core functionality—DREIDING force field parameterization including structure I/O, atom typing, charge calculation, and parameter generation—is now complete and passing all 121 tests. The objective of this issue is to transition the project from a functional codebase into a polished, well-documented library ready for public consumption. This involves three critical phases: auditing and formalizing the public API surface, implementing comprehensive RustDoc documentation with usage examples, and creating a professional README along with an architecture document to guide users and contributors. Completing this issue will signify that dreid-forge is ready for its first release on crates.io.

Tasks:

• Phase 1: Audit and Finalize Public API Surface

  • In src/lib.rs:
    • Review all module visibility (pub, pub(crate), private) across forge, io, and model modules.
    • Use pub use statements to re-export all essential public-facing types from the top level of the crate for a clean API surface, including:
      • Core forge API: forge, ForgeConfig, ChargeMethod, QeqConfig, SolverOptions
      • Potential type options: BondPotentialType, AnglePotentialType, VdwPotentialType
      • I/O types: ChemReader, ChemWriter, BioReader, BioWriter, Format
      • I/O config types: CleanConfig, ProtonationConfig, HisStrategy, SolvateConfig, TopologyConfig, Cation, Anion
      • LAMMPS output: write_lammps_package, write_lammps_data, write_lammps_settings, LammpsConfig, SystemType
      • BGF output: write_bgf
      • Template support: Template, read_mol2_template
      • Model types: System, Bond, Atom, Element, BondOrder
      • Topology types: ForgedSystem, AtomParam, Potentials, and all potential structs/enums
      • Metadata types: BioMetadata, AtomResidueInfo, StandardResidue, ResidueCategory, ResiduePosition
      • Error types: forge::Error, io::Error
    • Ensure internal helper functions and intermediate structures remain private.

• Phase 2: Implement Comprehensive API Documentation (RustDoc)

  • Crate-Level Documentation: In src/lib.rs, add //! comments at the top of the file. This documentation should include:
    • A high-level overview of what dreid-forge does and its role in the DREIDING ecosystem.
    • A brief explanation of the DREIDING force field and its applications.
    • A feature list covering: I/O formats, atom typing, charge calculation methods, potential types, and output formats.
    • A complete, runnable code example demonstrating the primary use case:
      • Reading a molecule from MOL2/SDF format
      • Calling forge() with a ForgeConfig
      • Writing output to LAMMPS data/settings files
    • A second example demonstrating biomolecule workflow:
      • Reading a PDB structure with BioReader
      • Applying cleaning, protonation, and solvation
      • Forging and outputting to BGF format
  • Module-Level Documentation: Add //! comments to each public module:
    • forge: Core parameterization engine and configuration
    • io: Input/output for molecular file formats
    • model: Data structures representing molecular systems and topologies
  • Public Item Documentation: Add /// comments to all public functions, structs, enums, and fields:
    • Document forge() function with detailed parameter explanations and error conditions
    • Document all ForgeConfig fields with their effects and default values
    • Document all I/O reader/writer types with format-specific notes
    • Document all potential types with their physical meaning and LAMMPS style equivalents
    • Document error types with guidance on handling each variant
  • Verification: Run cargo doc --open and ensure documentation is clear, complete, and renders correctly.

• Phase 3: Create README.md

  • Header Section:
    • Project name, brief tagline, and badges (crates.io version, docs.rs, license, build status)
  • Overview:
    • What is dreid-forge and what problem does it solve
    • Target audience (computational chemists, MD practitioners, materials scientists)
  • Features:
    • Supported input formats (PDB, mmCIF, MOL2, SDF)
    • Supported output formats (LAMMPS, BGF)
    • Atom typing via DREIDING rules (integration with dreid-typer)
    • Charge calculation (QEq via cheq)
    • Biomolecule support (protonation, solvation, disulfide bonds via bio-forge)
  • Quick Start:
    • Installation (Cargo.toml dependency)
    • Minimal working example for small molecules
    • Minimal working example for biomolecules
  • Configuration Guide:
    • Table of ForgeConfig options with descriptions
    • Table of potential type choices and their use cases
  • Custom Parameters:
    • How to provide custom force field parameters via TOML
    • How to provide custom typing rules
  • Links:
    • API documentation (docs.rs)
    • Related crates (dreid-typer, cheq, bio-forge)
    • DREIDING paper reference

• Phase 4: Create Architecture Documentation

  • Create docs/ARCHITECTURE.md with:
    • System Overview: High-level diagram showing the data flow from input to output
    • Module Structure: Description of forge, io, and model modules and their responsibilities
    • Core Pipeline: Detailed explanation of the forge() pipeline:
      1. IntermediateSystem construction
      2. Atom type assignment (wrapping dreid-typer)
      3. Charge calculation (wrapping cheq)
      4. Parameter generation (bonds, angles, dihedrals, impropers, vdW, H-bonds)
    • Data Models: Explanation of System vs ForgedSystem and when each is used
    • I/O Architecture: How BioReader/ChemReader differ and when to use each
    • Extension Points: How to add new formats or customize behavior
  • Dependency Diagram: Visual representation of how dreid-forge integrates with dreid-typer, cheq, and bio-forge