Larkinsd/feature energy injection

.claude/CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Installation and Setup
+- Avoid installing the package yourself. If you found a problem involving environment or need to test install, ask for help from the user.
+
+## Testing
+
+The project uses `pytest` for testing. Use a default timeout wall of 10 min.
+
+**IMPORTANT:** Avoid running `pytest` on the entire test suite, as it is very time-consuming. Instead, run specific tests or smaller groups of tests.
+
+### Running Tests
+
+The commands below are examples; you should replace file paths and test names with your actual targets.
+
+- **Run all tests in a file:**
+    `pytest test/structure/test_structure.py`
+- **Run a specific test function:**
+    `pytest test/structure/test_structure.py::test_deepcopy`
+- **Run tests by name pattern:**
+    `pytest -k "deepcopy"`
+
+IMPORTANT! Always run the unit test you wrote and make sure they passes so that the function is complete and working!
+
+## Architecture Overview
+
+EnzyHTP is a modular Python library for high-throughput enzyme modeling that automates molecular simulation workflows. The architecture follows a layered design with clear separation of concerns.
+
+### Core Architecture Principles
+- **Modular Design**: Each workflow component is encapsulated in its own module
+- **Interface Pattern**: Science APIs are decoupled from external tools via interface layer
+- **Structure-Centric**: Most operations work on `Structure` or `StructureEnsemble` objects
+- **Extensibility**: Easy to add new modules or replace existing implementations
+
+### Key Modules
+
+#### Core Data Structures
+The library is built around several key data types that represent different aspects of molecular systems:
+
+**Primary Structure Types (`enzy_htp/structure/`):**
+- `Structure` - Central data type representing complete enzyme structures. Its data structure is described in `DoubleLinkedNode`.
+- `StructureEnsemble` - Collections of structures for ensemble-based operations
+- `StructureRegion` - Specific regions within structures for targeted operations
+
+**Molecular Component Types:**
+- `Atom`, `Residue`, `Chain` - Hierarchical molecular building blocks
+- `Ligand`, `MetalAtom`, `Solvent` - Specialized molecular components
+- `ModifiedResidue`, `NoncanonicalBase` - Non-standard structural elements
+
+**Workflow Data Types:**
+- `Mutation` (`enzy_htp/mutation_class/`) - Represents amino acid substitutions
+- `ElectronicStructure` (`enzy_htp/electronic_structure/`) - Represents electronic structure and wavefunctions from quantum calculations
+- Interface handle types in `enzy_htp/_interface/handle_types/`
+
+**Structure Support Classes:**
+- Structure I/O, operations, selections, constraints, and translation utilities
+- Located in respective subdirectories under `enzy_htp/structure/`
+
+Most functions in this library operate on these data types, particularly `Structure` objects.
+
+#### Science APIs (High-level Workflow Modules)
+These modules provide the main scientific functionality and are designed to be extensible:
+
+**Current Science API Modules:**
+- `enzy_htp/preparation/` - Structure preparation, cleaning, protonation, docking
+- `enzy_htp/mutation/` - Amino acid substitutions and mutation pattern matching
+- `enzy_htp/geometry/` - Reaction geometry and conformational sampling
+- `enzy_htp/quantum/` - Quantum mechanics calculations and electronic structure
+- `enzy_htp/analysis/` - Post-simulation analysis (RMSD, binding, stability, clustering, etc.)
+
+**Workflow and Application Modules:**
+- `enzy_htp/workflow_app/` - Complete workflow applications for specific use cases
+- `enzy_htp/workflow_generation/` - Workflow configuration and execution management. (deporecated)
+
+**Extensibility Note:**
+New science API modules may be added in the future following the same patterns. Each typically contains:
+- Submodules containing Science APIs (functions typically have "Science API" in their docstring)
+- Clear separation from interface implementations
+
+#### Interface Layer (`enzy_htp/_interface/`)
+- Interfaces to external tools: Amber, Gaussian, Rosetta, PyMOL, RDKit, etc.
+- Configurations stored in `enzy_htp/_config/`
+- Science APIs use these interfaces but are not tightly coupled to them
+
+#### Support Modules
+- `enzy_htp/core/` - General utilities, file system, job management, clusters
+- `enzy_htp/chemical/` - Knowledge base (chemistry, atoms, residues, physics constants)
+
+## Code Conventions
+
+### Code Quality
+
+- MAKE SURE you write state-of-the-art quality code. Make it modular, robust, extensible, and maintainable.
+- `yapf --in-place <file_path>`: Formats a Python file using the project's `yapf` style.
+- **IMPORTANT:** Only use yapf for new files. For existing files, follow the established formatting to avoid unnecessary changes.
+
+### Key Patterns
+- Use interface pattern to avoid tight coupling with external tools
+- Test-driven development with tests mirroring source code structure
+- Type hints for function parameters and return values
+- Google Python Style Guide compliance with custom pylint configuration

.claude/commands/feedback.md

@@ -0,0 +1 @@
+There are some problems in your code changes. Here is my feedback: $ARGUMENTS. Please address them.

.claude/commands/repoinit.md

@@ -0,0 +1 @@
+Please read @.claude/CLAUDE.md to learn about the repo

.claude/commands/start_task.md

@@ -0,0 +1,2 @@
+You task in described in $ARGUMENTS.
+Read it and understand the task. Then work on it.

.claude/tasks/001-claude-plan.md

@@ -0,0 +1,134 @@
+# Analysis and Solution Plan for Structure Deepcopy Circular Reference Issue
+
+## CORRECTED Problem Analysis
+
+### Root Cause
+The issue is NOT that Structure lacks a custom deepcopy method. **Structure inherits from DoubleLinkedNode**, which DOES have a custom `__deepcopy__` method. The problem occurs because the DoubleLinkedNode's deepcopy method temporarily removes the custom deepcopy method and falls back to Python's default `copy.deepcopy`, which cannot handle circular references in the connectivity system.
+
+### Technical Details
+
+1. **Existing Custom Deepcopy**: The `Structure` class inherits from `DoubleLinkedNode` which has a custom `__deepcopy__` method (`enzy_htp/core/doubly_linked_tree.py:119-158`).
+
+2. **DoubleLinkedNode Deepcopy Logic**:
+   ```python
+   def __deepcopy__(self, memo: Union[Dict[int, Any], None] = None, _nil=[]):
+       # Handle parent-child relationships by setting parent to None in memo
+       # ... 
+       # CRITICAL ISSUE: Temporarily removes custom deepcopy method
+       self.__deepcopy__ = None
+
+       # Falls back to Python's default deepcopy - CANNOT handle circular references
+       new_self = copy.deepcopy(self, memo)
+
+       # Restore custom deepcopy method
+       delattr(self, "__deepcopy__")
+       delattr(new_self, "__deepcopy__")
+   ```
+
+3. **Circular References in Connectivity**: When `copy.deepcopy(self, memo)` is called on line 151 of DoubleLinkedNode, it uses Python's default deepcopy behavior which cannot handle the connectivity circular references:
+   - Each `Atom` has `_connect: List[Tuple[Atom, str]]` 
+   - When atom A connects to atom B: A._connect contains B, and B._connect contains A
+   - Default deepcopy fails with `RecursionError` on these circular references
+
+4. **Where Circular References Are Created**: In `enzy_htp/structure/structure_enchantment/connectivity.py:190`:
+   ```python
+   def _connect_caa_atom(atom: Atom) -> None:
+       # ... finds connected atoms ...
+       connect.append((cnt_atom, None))  # Creates reference to other atoms  
+       atom.connect = connect  # Stores bidirectional references causing circles
+   ```
+
+## Confirmed Behavior
+- **Before connectivity initialization**: DoubleLinkedNode deepcopy works (no circular references)
+- **After connectivity initialization**: Default deepcopy fails on connectivity circular references
+
+## Solution Plan
+
+### Option 1: Fix DoubleLinkedNode Deepcopy Method (Recommended)
+
+**Location**: `enzy_htp/core/doubly_linked_tree.py`
+
+**Problem**: The DoubleLinkedNode deepcopy method removes the custom `__deepcopy__` and falls back to default deepcopy, which cannot handle connectivity.
+
+**Solution**: Modify the DoubleLinkedNode deepcopy to handle connectivity circular references:
+
+```python
+def __deepcopy__(self, memo: Union[Dict[int, Any], None] = None, _nil=[]):
+    if memo is None:
+        memo = {}
+
+    # Handle parent relationships as before
+    if self.parent is not None:
+        parent_id = id(self.parent)
+        y = memo.get(parent_id, _nil)
+        if y is _nil:
+            memo[id(self.parent)] = None
+
+    # Instead of removing __deepcopy__, use a connectivity-aware approach
+    new_self = self._deepcopy_with_connectivity_handling(memo)
+    return new_self
+
+def _deepcopy_with_connectivity_handling(self, memo):
+    # Custom deepcopy logic that handles connectivity circular references
+    # 1. Create new instance
+    # 2. Copy non-connectivity attributes
+    # 3. Handle connectivity separately to break circular references
+    # 4. Rebuild connectivity with copied atom references
+```
+
+### Option 2: Override Deepcopy in Structure Class
+
+**Location**: `enzy_htp/structure/structure.py`
+
+**Implementation**: Override the inherited deepcopy method in Structure to handle connectivity:
+
+```python
+def __deepcopy__(self, memo):
+    # Call parent deepcopy but with connectivity handling
+    # or implement Structure-specific deepcopy that handles atoms with connectivity
+```
+
+### Option 3: Implement Connectivity-Aware Deepcopy at Atom Level  
+
+**Location**: `enzy_htp/structure/atom.py`
+
+**Implementation**: Add custom `__deepcopy__` to Atom class to handle its `_connect` attribute properly.
+
+## Recommended Implementation Plan
+
+### Phase 1: DoubleLinkedNode Fix (Option 1)
+1. **Modify DoubleLinkedNode's `__deepcopy__` method** to detect and handle connectivity circular references
+2. **Add connectivity-aware deepcopy logic** that temporarily removes connectivity, copies the structure, then rebuilds connectivity
+3. **Ensure compatibility** with all DoubleLinkedNode subclasses (Structure, Chain, Residue, Atom)
+
+### Phase 2: Testing and Validation  
+1. **Update `test_structure_deepcopy_isolation`** to verify the fix works
+2. **Test deepcopy with connectivity** on various structure types
+3. **Verify no regression** in parent-child relationship handling
+
+### Phase 3: Documentation
+1. **Document the connectivity handling** in DoubleLinkedNode deepcopy
+2. **Add unit tests** for deepcopy with various connectivity scenarios
+3. **Document known limitations** if any
+
+## Implementation Priority
+
+**High Priority**: Option 1 (Fix DoubleLinkedNode deepcopy)
+- Fixes the root cause in the base class
+- Benefits all DoubleLinkedNode subclasses
+- Maintains the existing inheritance pattern
+- Most comprehensive solution
+
+## Expected Outcome
+
+After implementation:
+- `copy.deepcopy(structure)` will work both before and after connectivity initialization
+- All DoubleLinkedNode subclasses will properly handle deepcopy with circular references
+- Integration tests that rely on structure copying will pass
+- Existing parent-child relationship handling is preserved
+
+## Files to Modify
+
+1. **Primary**: `enzy_htp/core/doubly_linked_tree.py` - Fix DoubleLinkedNode `__deepcopy__` method
+2. **Testing**: `test/structure/structure_enhancement/test_connectivity.py` - Update test expectations  
+3. **Additional**: Add unit tests for deepcopy with connectivity in various scenarios

.claude/tasks/001-feedback-1.md

@@ -0,0 +1,8 @@
+# Feedback for Claude Code
+
+Several problems in your code.
+    1. the unit test for test_amber_parameterizer_run_lv_5 is not passed
+    2. the unit test for test_run_prepgen is incomplete. You need to save an .ac file to the data directory associated with this test folder and use it. Reference other tests.
+    3. the generated .ac file is not using GAFF atom type which is by default. You need fix the wrong behavior in antechamber_ncaa_to_moldesc about atom_type. 
+    4. the _correct_atom_types_in_ac_file should not use ff14sb atom name mapping by default, you should at least have ff19sb atom name mapping there, and raise error if not in the mapping. You can find the lib file record these information under $AMBERHOME. Look for them.
+    5. the parm dat path should change according to the force field of choice. you can run tleap and just by sourcing the force field to see the associated parmdat path. There should always be a parmdat path mapped otherwise raise.

.claude/tasks/001-feedback-10.md

@@ -0,0 +1,25 @@
+# Plan
+
+The task is to make the `_parameterize_modified_res` more robust and use accurate force field.
+1. Before searh the ncaa library, we want to check if this maa is already supported by the force field user specified. Make a seperate function for this and call it. 
+    - This new function will be `check_residue_name_ff_support(res_code: str, force_fields: List[str], work_dir: Path) -> bool`
+    - res_code is the 3-letter code of the residue.
+    - In this function, we use a simple tleap call to verify the support. 
+        ```
+        # source all user specified force fields
+        source leaprc.protein.ff14SB
+        ...
+
+        # put the res code in 
+        model = sequence { RES }
+
+        # print out the description
+        desc model
+
+        quit
+        ```
+        explore what will happen with supported/unsupported case.
+    - make unit test for this function and do test driven development
+    - put it in `_parameterize_modified_res` and configure all the arguments using information we know in `_parameterize_modified_res`
+2. It is possible that user will use force field combinations such as ff19SB and ff19SB_modAA. Make sure `get_protein_force_field` if given such list find the correct canonincal AA protein force field. Add this case in the unit test and address any problem.
+

.claude/tasks/001-feedback-2.md

@@ -0,0 +1,6 @@
+# Feedback for Claude Code
+
+Several problems in your code.
+    1. the unit test for test_amber_parameterizer_run_lv_5 is not passed. You should read the error information and debug until it passes.
+    2. In amber_interface.py, the logic for finding the protein force field should be wrapped as a method. A list of supported force field should be stored as a class variable. (reference other mappers in AmberInterface)
+    3. ff19SB use XC for CA, I already made edit to the file and fixed it for you.

.claude/tasks/001-feedback-3.md

@@ -0,0 +1,9 @@
+# Feedback for Claude Code
+
+Several problems in your code.
+    1. Let's write a unit test try to isolate the deepcopy error happened in our lv 5 test.
+    2. get_protein_force_field need a unit test. You need to tests different possible input from user. Run the test and make the function more robust. For example, the function is not case sensitive to the input force_field, however should not, this should be addressed. Make sure the test passes.
+    3. In run_prepgen, os is already imported, remove the redundant import.
+    4. In run_prepgen, the error handling is not robust. Please keep any exception exposed.
+    5. The generated frcmod, frcmod2, mol2 file did not use the naming convention. Reference the convention in _parameterize_ligand. (i.e. you need to add target_method in the name.)
+    6. We need to make sure the "# 0. search parm lib - same as ligand" part of `_parameterize_modified_res` works. Read and understand how this works and write a seperate unit test to test this. (tip: you need to make the frcmod, frcmod2, mol2 files with the correct name and a new ncaa_lib_... dir under the associated data directory. dont forget the ones for RLP as well)

.claude/tasks/001-feedback-4.md

@@ -0,0 +1,7 @@
+# Feedback for Claude Code
+
+Several problems in your code.
+    1. The `run_prepgen` could hide error in the try block. I have edited the code to fix it. Review it and make sure it works. (i.e.: add a unit test in the case that will fail)
+    2. The existing unit test of run_prepgen need a rework. It now leaves intermediate files in the working dir and will not correct raise a failed prepgen run.
+    3. `test_structure_deepcopy_isolation` should not be in `test_amber_interface` because it has nothing to do with Amber. Put it in the right place.
+    4. Propose a plan to fix the deepcopy problem isolated in `test_structure_deepcopy_isolation`. Write the plan in a new file under `.claude/tasks/001-claude-plan-{index}.md`. You should come up with several plans index them in the filename.

.claude/tasks/001-feedback-5.md

@@ -0,0 +1,9 @@
+# Feedback for Claude Code
+
+Several problems in your code.
+    1. `test_run_prepgen` need a rework. You need to generate a .mc file and keep it in the data dir. (i.e. using a seperate run.) And avoid generating the .mc file during the test. I have deleted everything in that unit test. Please plan what to test first and complete it and make it work.
+    2. For fixing the problem isolated in `test_structure_deepcopy_isolation`. Please 
+       a. read and understand the current custom deepcopy method Structure class use
+       b. read and understand how connectivity is stored in Structure
+       c. based on your understanding analyze the reason of the problem
+       d. write your analysis of the reason and a concrete plan about what changes should be made on the custom deepcopy function under `.claude/tasks/001-claude-plan.md`

.claude/tasks/001-feedback-6.md

@@ -0,0 +1,12 @@
+# Feedback for Claude Code
+
+Several problems in your code.
+    1. `run_prepgen` need to clean up the generated intermediate files. Use `test_run_prepgen` to figure out what files need to be cleaned and change `run_prepgen` to clean them.
+    !! RUN unit tests related to this problem. Create unit test when it is necessary. A problem is only considered resolved when the related unit test passes.
+    2. You preivous understanding of the problem isolated in `test_structure_deepcopy_isolation` is wrong. There is a custom deepcopy method defined in the parent class of Structure: `DoubleLinkedNode` 
+       a. read and understand the current custom deepcopy method Structure class use
+       b. read and understand how connectivity is stored in Structure
+       c. based on your understanding analyze the reason of the problem
+       d. update `.claude/tasks/001-claude-plan.md` for your new understanding and plan to fix
+
+

.claude/tasks/001-feedback-7.md

@@ -0,0 +1,14 @@
+# Feedback for Claude Code
+
+Several problems in your code.
+    1. `test_run_prepgen` is wrong. I have fixed it for you. The reason that it failed previously is because you used a broken `ac` and `mc` files. Please add code in `run_prepgen` to expose any error information it reports.
+       a. make broken .ac file or .mc file.
+       b. manually run prepgen to see what error informtaion is given.
+       c. change `run_prepgen` to report these errors.
+       b. make sure the error handling is working by definig them in `test_run_prepgen_failure_cases` and make sure it passes.
+    2. You preivous understanding of the problem isolated in `test_structure_deepcopy_isolation` is wrong. I have fixed the the `__deepcopy__` method in `DoubleLinkedNode` and explained in `test_connected_structure_deepcopy`. You need to read the TODO I left in this test function and complete the test function.
+    3. As the deepcopy problem addressed, you should make sure `test_amber_parameterizer_run_lv_5` works so that the maa support is complete. I commented out the clean up line in this test so that I can check your result.
+
+!! RUN unit tests related to this problem. Create unit test when it is necessary. A problem is only considered resolved when the related unit test passes.
+
+