Conversation
…for hybrid biological systems
…rid charge methods
…rget pH is set in system metadata
…ing biological metadata
… Option for insertion codes
… and improve parameter handling
… damping strategy
… charge distribution analysis for 5HKR example
…h default behavior
TKanX
added
documentation 📖
24 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request implements a hybrid electrostatics system for biological simulations by combining classical force field charges (AMBER/CHARMM) for standard biomolecules with QEq charge equilibration for ligands and hetero groups. The implementation includes environmental field polarization through an "embedded" QEq mode that accounts for electrostatic potential from surrounding fixed-charge atoms.
Changes:
- Refactored charge calculation module into separate submodules (qeq, hybrid, spatial)
- Integrated
ffchargecrate for classical force field charge assignment - Implemented embedded QEq with spatial grid optimization for efficient neighbor lookups
- Enhanced CLI with granular hybrid charge configuration options
- Changed
chain_idfromchartoStringandinsertion_codefromchartoOption<char>for better PDB/mmCIF compatibility - Added
target_phfield toBioMetadatafor pH-dependent protonation state handling
Reviewed changes
Copilot reviewed 25 out of 37 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| src/model/metadata.rs | Updated chain_id to String, insertion_code to Option, added target_ph and effective_ph() |
| src/io/util.rs | Propagated chain_id/insertion_code type changes through conversion functions |
| src/io/pdb/reader.rs | Added target_ph propagation from protonation config to BioMetadata |
| src/io/mmcif/reader.rs | Added target_ph propagation from protonation config to BioMetadata |
| src/io/bgf/writer.rs | Updated for chain_id/insertion_code type changes, converts String to char for BGF format |
| src/forge/config/mod.rs | New module structure exposing all config types including hybrid-specific ones |
| src/forge/config/charge.rs | New file defining ChargeMethod, QeqConfig, HybridConfig, and related types |
| src/forge/config/potential.rs | New file separating potential type enums from main config |
| src/forge/charge/qeq.rs | Extracted QEq implementation into dedicated module |
| src/forge/charge/hybrid.rs | New implementation of hybrid charge assignment with atom classification and embedded QEq |
| src/forge/charge/spatial.rs | New spatial grid data structure for O(1) neighbor queries |
| src/forge/intermediate.rs | Added bio_metadata field and effective_ph() helper method |
| src/forge/error.rs | Added MissingBioMetadata and HybridChargeAssignment error variants |
| src/forge/paramgen.rs | Updated to handle Hybrid charge method for hydrogen bond parameters |
| src/bin/dforge/cli.rs | Restructured CLI with ChargeOptions, HybridChargeOptions, QeqSolverOptions, and PotentialOptions |
| src/bin/dforge/config/forge.rs | Split into build_bio_forge_config and build_chem_forge_config |
| src/bin/dforge/config/bio.rs | Updated to pass Option for pH instead of unwrapping |
| src/bin/dforge/util/convert.rs | Added extensive conversion logic for hybrid config and force field schemes |
| src/bin/dforge/commands/bio.rs | Updated to use new config structure and display hybrid charge information |
| src/bin/dforge/commands/chem.rs | Updated to use new config structure |
| examples/complex/README.md | Added comprehensive examples demonstrating hybrid charge calculations with pH effects |
| README.md | Updated with hybrid charge example and dependency information |
| MANUAL.md | Extensive documentation of hybrid charge options and QEq solver tuning |
| ARCHITECTURE.md | Added detailed diagrams and explanations of hybrid charge workflow |
| Cargo.toml | Version bump to 0.3.0, updated dependencies (bio-forge 0.3.1, cheq 0.5.0, ffcharge 0.2.0) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
TKanX
deleted the
feature/11-refactor-charge-engine-for-hybrid-biological-electrostatics
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary:
Refactored the charge calculation system to support a "Hybrid" mode, enabling high-fidelity electrostatics for biological systems. This engine integrates the
ffchargecrate to assign classical force field charges (AMBER/CHARMM/TIP3P) to standard biomolecules (proteins, nucleic acids, water, ions), while reserving QEq charge equilibration for ligands and hetero groups. This approach combines the accuracy of established force fields for macromolecules with the flexibility of QEq for novel drug-like molecules.Changes:
Integrated
ffchargeCrate:ffchargedependency to provide a database of standard partial charges from major force fields (AMBER ff99SB/ff14SB, CHARMM36, TIP3P/SPC water models).HybridConfigto allow user selection of protein, nucleic acid, and water charge schemes.Implemented Hybrid Charge Strategy:
src/forge/charge/hybrid.rsto classify atoms as Protein, Nucleic Acid, Water, Ion, or Ligand based onBioMetadata.ffchargeto standard residues, respecting pH-dependent terminal protonation states (N-terminus/C-terminus).Developed Embedded QEq:
LigandQeqMethod::Embedded) where ligand charges are polarized by the electrostatic field of the surrounding protein environment.src/forge/charge/spatial.rswith aSpatialGridfor efficient O(1) neighbor lookups to identify environment atoms within a cutoff radius.cheq'ssolve_in_fieldAPI to include external point charges in the equilibration process.Enhanced CLI Support:
dforge bioto support--charge hybridwith granular configuration flags:--protein-scheme,--nucleic-scheme,--water-schemefor selecting force fields.--ligand <CHAIN:RESID>syntax for targeting specific ligands with custom QEq settings (vacuum vs. embedded).--qeq-tolerance,--qeq-damping,--qeq-hydrogen-scf) exposed to the CLI.Refactored Charge Module:
src/forge/charge/into submodules (qeq,hybrid,spatial) for better separation of concerns.ForgeConfigandChargeMethodenums to accommodate the new hybrid configuration structures.Documentation & Examples:
MANUAL.mdwith detailed explanations of the hybrid charge workflow and configuration examples.ARCHITECTURE.mdwith diagrams illustrating the hybrid dispatch logic and embedded QEq data flow.examples/complex/demonstrating hybrid charging of a fullerene-protein complex, including analysis of pH-dependent polarization effects.