Refactor `LevelManager` and Modularize Hierarchical Entropy Computations

[harryswift01]

Description

The current LevelManager class has grown too large and handles multiple responsibilities, including managing levels, beads, coordinates, dihedrals, matrices, forces, and torques. This makes the code difficult to maintain, test, and extend.

This task aims to modularize the class into focused components and introduce a graph/DAG-based representation of hierarchical dependencies. This will simplify computations, reduce repeated loops, and make it easier to add new entropy estimates in the future.

Scope

• Split LevelManager into multiple classes:
  • LevelHierarchy: manages levels and beads.
  • CoordinateSystem: computes axes, average positions, and coordinate transformations.
  • StructuralAnalysis: handles dihedrals and structural metrics.
  • MatrixOperations: handles submatrices and matrix utilities.
  • ForceTorqueManager: calculates weighted forces and torques.
• Implement a DAG-based computation order for hierarchical entropy calculations.
• Refactor existing methods into these classes without changing external behavior.
• Ensure LevelManager acts only as a coordinator.
• Update internal documentation and APIs.

Tasks

• Map current LevelManager methods to the proposed modular classes.
• Implement LevelHierarchy to manage levels and beads.
• Implement CoordinateSystem for axes and position calculations.
• Implement StructuralAnalysis for dihedral and structural calculations.
• Implement MatrixOperations for submatrix and matrix handling.
• Implement ForceTorqueManager for weighted force and torque calculations.
• Introduce DAG-based representation of levels and beads to pre-map dependencies.
• Update LevelManager to coordinate modular components and DAG-based computation.
• Unit test each new class independently.
• Document new architecture and DAG-based workflow.

Benefits

• Single Responsibility Principle: Each class has one clear responsibility.
• Testability: Easier to write unit tests and verify calculations.
• Maintainability: Refactoring or adding new features is safer and easier.
• Scalability: DAG ensures correct computation order and reduces redundant calculations.
• Future-Proofing: Adding new entropy estimates is straightforward using existing modular classes and DAG traversal.

[harryswift01]

After an initial review of the existing codebase and an attempt to abstract functionality out of the Levels class, this is a proposed file and class structure aimed at reducing complexity and preventing further class bloat.

CodeEntropy/
├── CodeEntropy/
│   ├── __init__.py
│   │
│   ├── config/
│   │   ├── __init__.py
│   │   ├── run_manager.py          # Runs workflows, manages IO and configurations
│   │   ├── arg_config_manager.py       # Parses YAML/JSON configs and CLI args
│   │   ├── data_logger.py          # Stores entropy outputs and summaries
│   │   ├── logging_config.py       # Logging setup and log level management
│   │   └── utils/
│   │       ├── __init__.py
│   │       ├── math_utils.py       # Common NumPy opserations, matrix filters, vector norms
│   │       └── io_utils.py         # File reading/writing helpers
│   │
│   ├── levels/
│   │   ├── __init__.py
│   │   ├── level_manager.py        # High-level orchestrator for level computations
│   │   ├── level_hierarchy.py      # Class: LevelHierarchy - manages levels and beads
│   │   ├── coordinate_system.py    # Class: CoordinateSystem - computes axes & coordinates
│   │   ├── structural_analysis.py  # Class: StructuralAnalysis - dihedrals & structure
│   │   ├── matrix_operations.py    # Class: MatrixOperations - builds & filters matrices
│   │   ├── force_torque_manager.py # Class: ForceTorqueManager - forces and torques
│   │   └── hierarchy_graph.py      # DAG of hierarchical levels (atoms→residues→molecules)
│   │
│   ├── entropy/
│   │   ├── __init__.py
│   │   ├── entropy_manager.py      # Orchestrates entropy computation using DAG
│   │   ├── entropy_graph.py        # Defines and executes DAG using NetworkX
│   │   ├── entropy_aggregator.py   # Combines results from all entropy nodes
│   │   ├── visualisation.py        # DAG visualization and dependency debugging
│   │   └── nodes/
│   │       ├── __init__.py
│   │       ├── matrix_builder.py
│   │       ├── force_calculator.py
│   │       ├── vibrational_entropy.py
│   │       ├── configurational_entropy.py
│   │       ├── orientational_entropy.py
│   │       └── entropy_node_base.py         # Base class for DAG nodes
│   │
│   ├── group_molecules/
│   │   ├── __init__.py
│   │   └── group_molecules.py      # Molecule grouping logic
│   │
│   └── cli/
│       ├── __init__.py
│       └── main.py                 # CLI entry point (e.g., `CodeEntropy`, `CodeEntropy --regression_test`)

[harryswift01]

Mapping of existing LevelManager functions to the proposed modular classes:

• level_hierarchy.py → LevelHierarchy

  • get_beads()
  • select_levels()

• coordinate_system.py → CoordinateSystem

  • get_avg_pos()
  • get_axes()
  • get_sphCoord_axes()

• dihedral_analysis.py → DihedralAnalysis

  • get_dihedrals()
  • compute_dihedral_conformations()
  • build_conformational_states()

• matrix_operations.py → MatrixOperations

  • create_submatrix()
  • filter_zero_rows_columns()
  • get_matrices()

• force_torque_manager.py → ForceTorqueManager

  • get_weighted_forces()
  • get_weighted_torques()
  • build_covariance_matrices()

• level_manager.py → LevelManager

  • __init__()
  • Orchestrates calls to all of the above classes

This layout breaks down the original monolithic LevelManager into clear, single-responsibility components.

[skfegan]

One change - I think what you have as StructuralAnalysis should be DihedralAnalysis and then we will add a new class for Neighbours.

the build_covariance_matrices() function should go with the get_weighted_forces() and get_weighted_torques()

[harryswift01]

One change - I think what you have as StructuralAnalysis should be DihedralAnalysis and then we will add a new class for Neighbours.

the build_covariance_matrices() function should go with the get_weighted_forces() and get_weighted_torques()

This sounds good, I can make those changes now.