Skip to content

Refactor LevelManager and Modularize Hierarchical Entropy Computations #173

Closed
Feature
#281
Closed
Refactor LevelManager and Modularize Hierarchical Entropy Computations#173
Feature
#281
Assignees
harryswift01
Labels
feature requestNew feature or request
Milestone
v2.0.0

Description

@harryswift01
harryswift01
opened on Oct 29, 2025

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.

Activity

  1. harryswift01
    added this to the v1.0.4 milestone on Oct 29, 2025
  2. harryswift01
    self-assigned this
    on Oct 29, 2025
  3. harryswift01
    added the
    Feature
    issue type on Oct 29, 2025
  4. harryswift01
    added
    feature requestNew feature or request
    on Oct 29, 2025

  5. harryswift01 commented on Oct 30, 2025

    @harryswift01
    harryswift01
    on Oct 30, 2025
    MemberAuthor

    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`)

  6. harryswift01 commented on Oct 30, 2025

    @harryswift01
    harryswift01
    on Oct 30, 2025
    MemberAuthor

    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.

  7. harryswift01
    pinned this issue on Oct 30, 2025
  8. harryswift01
    unpinned this issue on Oct 30, 2025
  9. harryswift01
    modified the milestones: v1.0.4, v1.1.0 on Oct 31, 2025

  10. skfegan commented on Nov 5, 2025

    @skfegan
    skfegan
    on Nov 5, 2025
    Member

    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()

  11. harryswift01 commented on Nov 5, 2025

    @harryswift01
    harryswift01
    on Nov 5, 2025
    MemberAuthor

    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.

  12. harryswift01
    linked a pull request that will close this issueRefactor workflow to DAG architecture with expanded testing, CI modernisation, and validated numerical equivalence #281on Feb 25, 2026
  13. harryswift01
    closed this as completedin #281on Feb 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

feature requestNew feature or request

Type

Feature

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions