EntDetect 1.2.0__py3-none-any.whl

scripts/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line entry points for EntDetect.
+
+These modules are primarily thin wrappers around the core library in
+`EntDetect/`.
+"""

scripts/convert_cor_psf_to_pdb.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Convert CHARMM COR and PSF files to PDB format.
+
+Usage:
+    python scripts/convert_cor_psf_to_pdb.py --cor structure.cor --psf structure.psf --output structure.pdb
+
+This script uses MDAnalysis to read CHARMM coordinate (.cor/.crd) and topology (.psf) files
+and writes them as a single PDB file that can be used with EntDetect analysis tools.
+"""
+
+import argparse
+import os
+import sys
+
+def convert_cor_psf_to_pdb(cor_file, psf_file, output_pdb):
+    """
+    Convert CHARMM COR and PSF files to PDB format.
+    
+    Parameters
+    ----------
+    cor_file : str
+        Path to CHARMM coordinate file (.cor or .crd)
+    psf_file : str
+        Path to CHARMM PSF topology file (.psf)
+    output_pdb : str
+        Path to output PDB file
+    """
+    try:
+        import MDAnalysis as mda
+    except ImportError:
+        print("Error: MDAnalysis is required for this conversion.")
+        print("Install with: pip install MDAnalysis")
+        sys.exit(1)
+    
+    # Validate input files exist
+    if not os.path.exists(cor_file):
+        print(f"Error: COR file not found: {cor_file}")
+        sys.exit(1)
+    if not os.path.exists(psf_file):
+        print(f"Error: PSF file not found: {psf_file}")
+        sys.exit(1)
+    
+    print(f"Reading topology from: {psf_file}")
+    print(f"Reading coordinates from: {cor_file}")
+    
+    # Load the structure with PSF topology and COR coordinates
+    u = mda.Universe(psf_file, cor_file)
+    
+    print(f"Loaded structure with {len(u.atoms)} atoms")
+    
+    # Set chainID to 'A' for all atoms if not already set
+    if not hasattr(u.atoms, 'chainIDs') or all(c == '' or c == 'X' for c in u.atoms.chainIDs):
+        print("Setting chainID to 'A' for all atoms")
+        u.add_TopologyAttr('chainIDs', ['A'] * len(u.atoms))
+    
+    # Write to PDB format
+    print(f"Writing PDB to: {output_pdb}")
+    u.atoms.write(output_pdb)
+    
+    print("Conversion complete!")
+    return output_pdb
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="Convert CHARMM COR/PSF files to PDB format",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  convert_cor_psf_to_pdb --cor model.cor --psf model.psf --output model.pdb
+  convert_cor_psf_to_pdb --cor 1zmr_ca.crd --psf 1zmr_ca.psf --output 1zmr_ca.pdb
+        """,
+    )
+
+    parser.add_argument(
+        "--cor",
+        "--crd",
+        type=str,
+        required=True,
+        help="Input CHARMM coordinate file (.cor or .crd)",
+    )
+    parser.add_argument(
+        "--psf",
+        type=str,
+        required=True,
+        help="Input CHARMM PSF topology file (.psf)",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=str,
+        required=True,
+        help="Output PDB file",
+    )
+
+    args = parser.parse_args(argv)
+    convert_cor_psf_to_pdb(args.cor, args.psf, args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/run_Foldingpathway.py

@@ -0,0 +1,162 @@
+from EntDetect.statistics import FoldingPathwayStats
+from EntDetect._logging import setup_logger
+import pandas as pd
+
+"""
+Compute folding pathway statistics and Jensen-Shannon divergence from an MSM
+trajectory-type-annotated mapping CSV produced by run_MSM.py.
+
+The input --msm_data_file must be a CSV with the columns produced by run_MSM.py
+(traj, frame, microstate, metastablestate, Q, G, StateSample) plus a user-added
+trajectory-type column (--traj_type_col) that labels each trajectory as belonging
+to one of the types in --traj_type_list (e.g. 'A' for folded, 'B' for unfolded).
+
+This classification is typically added by the user based on a Q threshold, e.g.:
+  df['traj_type_A80%Native'] = df.groupby('traj')['Q'].transform('max').ge(0.80).map({True:'A', False:'B'})
+
+Examples
+--------
+Basic run — two trajectory types, no exclusions:
+  python scripts/run_Foldingpathway.py \\
+    --msm_data_file $DATASTORE/outputs/workflow2/MSM/1ZMR_prod_MSMmapping_A80pctNative.csv \\
+    --meta_set_file $DATASTORE/outputs/workflow2/MSM/1ZMR_prod_meta_set.csv \\
+    --traj_type_col traj_type_A80pctNative \\
+    --traj_type_list A B \\
+    --outdir        $DATASTORE/outputs/workflow2/FoldingPathway_A80pctNative
+
+Excluding mirror-image trajectories identified in Step 4:
+  python scripts/run_Foldingpathway.py \\
+    --msm_data_file $DATASTORE/outputs/workflow2/MSM/1ZMR_prod_MSMmapping_A80pctNative.csv \\
+    --meta_set_file $DATASTORE/outputs/workflow2/MSM/1ZMR_prod_meta_set.csv \\
+    --traj_type_col traj_type_A80pctNative \\
+    --traj_type_list A B \\
+    --outdir        $DATASTORE/outputs/workflow2/FoldingPathway_A80pctNative \\
+    --rm_traj_list  65 75 155 162
+
+Flags
+-----
+  --msm_data_file   CSV produced by run_MSM.py, annotated with a trajectory-type column
+  --meta_set_file   meta_set CSV produced by run_MSM.py (microstates per metastable state)
+  --traj_type_col   Column name in msm_data_file that contains trajectory-type labels
+  --traj_type_list  Space-separated list of trajectory-type labels to compare (default: A B)
+  --outdir          Output directory for folding pathway and JS-divergence results
+  --rm_traj_list    Trajectory numbers to exclude (e.g. confirmed mirror conformations)
+  --n_window        Rolling window size for state probability smoothing (default: 200)
+  --n_traj          Total number of trajectories in the ensemble (default: 1000)
+  --state_type      State level to analyse: metastablestate or microstate (default: metastablestate)
+  --log_level       Logging verbosity: DEBUG, INFO, WARNING, ERROR (default: INFO)
+  --logdir          Directory for log file (default: same as --outdir)
+"""
+
+
+def main(argv=None):
+
+    ###---------------------------------------------------------------------------------------------------------
+    import sys, os
+    import argparse
+    import time
+    import logging
+    start_time = time.time()
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    parser = argparse.ArgumentParser(
+        description="Compute folding pathway statistics and Jensen-Shannon divergence from MSM output.")
+
+    # --- IO ---
+    parser.add_argument("--msm_data_file", type=str, required=True,  help="CSV produced by run_MSM.py, annotated with a trajectory-type column")
+    parser.add_argument("--meta_set_file", type=str, required=True,  help="meta_set CSV produced by run_MSM.py")
+    parser.add_argument("--outdir",        type=str, required=True,  help="Output directory for folding pathway and JS-divergence results")
+
+    # --- trajectory classification ---
+    parser.add_argument("--traj_type_col",  type=str,          required=True,        help="Column name in msm_data_file containing trajectory-type labels")
+    parser.add_argument("--traj_type_list", type=str, nargs='+', default=['A', 'B'], help="Trajectory-type labels to compare (default: A B)")
+
+    # --- trajectory filtering ---
+    parser.add_argument("--rm_traj_list", type=int, nargs='+', default=[], help="Trajectory numbers to exclude (e.g. confirmed mirror conformations)")
+
+    # --- analysis settings ---
+    parser.add_argument("--n_window",   type=int, default=200,              help="Rolling window size for state probability smoothing (default: 200)")
+    parser.add_argument("--n_traj",     type=int, default=1000,             help="Total number of trajectories in the ensemble (default: 1000)")
+    parser.add_argument("--state_type", type=str, default='metastablestate',
+                        choices=['metastablestate', 'microstate'],          help="State level to analyse (default: metastablestate)")
+
+    # --- logging ---
+    parser.add_argument("--log_level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR"], help="Logging verbosity (default: INFO)")
+    parser.add_argument("--logdir",    type=str, default=None, help="Directory for log file (default: same as --outdir)")
+
+    args = parser.parse_args(argv)
+
+    outdir = args.outdir
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    log_level = getattr(logging, args.log_level.upper(), logging.INFO)
+    logdir    = args.logdir if args.logdir is not None else outdir
+
+    os.makedirs(outdir, exist_ok=True)
+
+    logger = setup_logger('run_Foldingpathway', outdir=logdir, ID='FoldingPathwayStats', log_level=log_level)
+    setup_logger('FoldingPathwayStats', outdir=logdir, ID='FoldingPathwayStats', log_level=log_level)
+    logger.info(f'args: {args}')
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    # --- input validation ---
+    if not os.path.isfile(args.msm_data_file):
+        parser.error(f"--msm_data_file does not exist: {args.msm_data_file}")
+
+    if not os.path.isfile(args.meta_set_file):
+        parser.error(f"--meta_set_file does not exist: {args.meta_set_file}")
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    # Load MSM data and validate the trajectory-type column
+    logger.info(f'Loading MSM data from {args.msm_data_file}')
+    msm_data = pd.read_csv(args.msm_data_file)
+    logger.info(f'msm_data shape: {msm_data.shape}, columns: {msm_data.columns.tolist()}')
+
+    if args.traj_type_col not in msm_data.columns:
+        parser.error(
+            f"--traj_type_col '{args.traj_type_col}' not found in {args.msm_data_file}. "
+            f"Available columns: {msm_data.columns.tolist()}"
+        )
+
+    present_types = set(msm_data[args.traj_type_col].unique())
+    missing_types = [t for t in args.traj_type_list if t not in present_types]
+    if missing_types:
+        parser.error(
+            f"--traj_type_list values {missing_types} not found in column '{args.traj_type_col}'. "
+            f"Values present: {sorted(present_types)}"
+        )
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    FP = FoldingPathwayStats(
+        msm_data=msm_data,
+        meta_set_file=args.meta_set_file,
+        tarj_type_col=args.traj_type_col,
+        traj_type_list=args.traj_type_list,
+        outdir=outdir,
+        n_window=args.n_window,
+        n_traj=args.n_traj,
+        state_type=args.state_type,
+        rm_traj_list=args.rm_traj_list,
+        log_level=log_level,
+        logdir=logdir,
+    )
+    logger.info(f'FoldingPathwayStats: {FP}')
+
+    folding_pathways = FP.post_trans()
+    logger.info(f'folding_pathways:\n{folding_pathways}')
+
+    JS_divergence = FP.JS_divergence()
+    logger.info(f'JS_divergence:\n{JS_divergence}')
+    ###---------------------------------------------------------------------------------------------------------
+
+    logger.info(f'NORMAL TERMINATION - {time.time() - start_time:.1f} seconds')
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/run_MSM.py

@@ -0,0 +1,152 @@
+from EntDetect.clustering import MSMNonNativeEntanglementClustering
+from EntDetect._logging import setup_logger
+
+"""
+Build a Markov state model (MSM) from pre-computed order-parameter data across
+an ensemble of simulation trajectories.
+
+Reads Q and G order-parameter files from --OPpath (which must contain Q/ and G/
+subdirectories produced by run_OP_on_simulation_traj.py), groups frames into
+microstates via k-means clustering, and then coarse-grains microstates into
+metastable macro-states using PCCA+.
+
+Examples
+--------
+Basic run — 10 metastable states, lag time 20:
+  python scripts/run_MSM.py \\
+    --outdir  $DATASTORE/outputs/workflow2/MSM \\
+    --ID      1ZMR_prod \\
+    --OPpath  $DATASTORE/outputs/workflow2/OP_demo/ \\
+    --start   0 \\
+    --n_large_states 10 \\
+    --lagtime 20
+
+Excluding mirror-image trajectories (identified in Step 10):
+  python scripts/run_MSM.py \\
+    --outdir  $DATASTORE/outputs/workflow2/MSM \\
+    --ID      1ZMR_prod \\
+    --OPpath  $DATASTORE/outputs/workflow2/OP_demo/ \\
+    --start   0 \\
+    --n_large_states 10 \\
+    --lagtime 20 \\
+    --rm_traj_list 65 75 155 162
+
+Flags
+-----
+  --outdir           Output directory for MSM results
+  --OPpath           Directory containing Q/ and G/ subdirectories of per-trajectory OP files
+  --ID               Base name for output files
+  --start            First frame index to include, 0-based (default: 0)
+  --end              Last frame index to include, 0-based (default: all frames)
+  --stride           Frame stride for loading OP data (default: 1)
+  --n_large_states   Number of metastable macro-states requested from PCCA+ (default: 10)
+  --n_small_states   Number of inactive micro-state clusters (default: 1)
+  --n_cluster        Number of k-means microstates (default: 400)
+  --kmean_stride     Frame stride used during k-means clustering (default: 2)
+  --lagtime          MSM lag time in frames (default: 20)
+  --dt               MD timestep in ns, used for time-axis labelling (default: 1.5e-5)
+  --ITS              Run implied timescale analysis to validate lag time: True/False (default: False)
+  --rm_traj_list     Trajectory numbers to exclude (e.g. confirmed mirror conformations)
+  --log_level        Logging verbosity: DEBUG, INFO, WARNING, ERROR (default: INFO)
+  --logdir           Directory for log file (default: same as --outdir)
+"""
+
+
+def main(argv=None):
+
+    ###---------------------------------------------------------------------------------------------------------
+    import sys, os
+    import argparse
+    import time
+    import logging
+    start_time = time.time()
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    parser = argparse.ArgumentParser(
+        description="Build a Markov state model from pre-computed order-parameter trajectories.")
+
+    # --- identity / IO ---
+    parser.add_argument("--outdir",  type=str, required=True,  help="Output directory for MSM results")
+    parser.add_argument("--OPpath",  type=str, required=True,  help="Directory containing Q/ and G/ subdirectories of per-trajectory OP files")
+    parser.add_argument("--ID",      type=str, required=True,  help="Base name for output files")
+
+    # --- frame selection ---
+    parser.add_argument("--start",   type=int, default=0,           help="First frame index to include, 0-based (default: 0)")
+    parser.add_argument("--end",     type=int, default=99999999999, help="Last frame index to include, 0-based (default: all frames)")
+    parser.add_argument("--stride",  type=int, default=1,           help="Frame stride for loading OP data (default: 1)")
+
+    # --- MSM settings ---
+    parser.add_argument("--n_large_states", type=int,   default=10,          help="Number of metastable macro-states requested from PCCA+ (default: 10)")
+    parser.add_argument("--n_small_states", type=int,   default=1,           help="Number of inactive micro-state clusters (default: 1)")
+    parser.add_argument("--n_cluster",      type=int,   default=400,         help="Number of k-means microstates (default: 400)")
+    parser.add_argument("--kmean_stride",   type=int,   default=2,           help="Frame stride used during k-means clustering (default: 2)")
+    parser.add_argument("--lagtime",        type=int,   default=20,          help="MSM lag time in frames (default: 20)")
+    parser.add_argument("--dt",             type=float, default=0.015/1000,  help="MD timestep in ns (default: 1.5e-5)")
+    parser.add_argument("--ITS",            type=str,   default='False',     help="Run implied timescale analysis: True/False (default: False)")
+
+    # --- trajectory filtering ---
+    parser.add_argument("--rm_traj_list", type=int, nargs='+', default=[], help="Trajectory numbers to exclude (e.g. confirmed mirror conformations)")
+
+    # --- logging ---
+    parser.add_argument("--log_level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR"], help="Logging verbosity (default: INFO)")
+    parser.add_argument("--logdir",    type=str, default=None, help="Directory for log file (default: same as --outdir)")
+
+    args = parser.parse_args(argv)
+
+    outdir = args.outdir
+    OPpath = args.OPpath
+    ID     = args.ID
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    log_level = getattr(logging, args.log_level.upper(), logging.INFO)
+    logdir    = args.logdir if args.logdir is not None else outdir
+
+    logger = setup_logger('run_MSM', outdir=logdir, ID=ID, log_level=log_level)
+    setup_logger('MSMNonNativeEntanglementClustering', outdir=logdir, ID=ID, log_level=log_level)
+    logger.info(f'args: {args}')
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    # --- input validation ---
+    if not os.path.isdir(OPpath):
+        parser.error(f"--OPpath does not exist or is not a directory: {OPpath}")
+
+    for subdir in ('Q', 'G'):
+        expected = os.path.join(OPpath, subdir)
+        if not os.path.isdir(expected):
+            parser.error(f"Expected subdirectory not found in --OPpath: {expected}")
+
+    os.makedirs(outdir, exist_ok=True)
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    MSM = MSMNonNativeEntanglementClustering(
+        outdir=outdir,
+        ID=ID,
+        OPpath=OPpath,
+        start=args.start,
+        end=args.end,
+        stride=args.stride,
+        n_large_states=args.n_large_states,
+        n_small_states=args.n_small_states,
+        n_cluster=args.n_cluster,
+        kmean_stride=args.kmean_stride,
+        lagtime=args.lagtime,
+        dt=args.dt,
+        ITS=args.ITS,
+        rm_traj_list=args.rm_traj_list,
+        log_level=log_level,
+        logdir=logdir,
+    )
+    logger.info(f'MSMNonNativeEntanglementClustering: {MSM}')
+    MSM.run()
+    ###---------------------------------------------------------------------------------------------------------
+
+    logger.info(f'NORMAL TERMINATION - {time.time() - start_time:.1f} seconds')
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/run_OP_on_simulation_traj.py

@@ -0,0 +1,194 @@
+from EntDetect.order_params import CalculateOP
+from EntDetect._logging import setup_logger
+
+"""
+Calculate any combination of order parameters on CG and/or all-atom trajectories.
+
+Available OPs:  Q  G  K  SASA  XP
+  Q    — fraction of native contacts
+  G    — fraction of native contacts with a change of entanglement (+ entanglement features)
+  K    — mirror symmetry order parameter
+  SASA — solvent accessible surface area  (requires all-atom trajectory)
+  XP   — Jwalk cross-link probability     (requires all-atom trajectory + --xp_pdb)
+
+For SASA/XP the all-atom trajectory is used; set --resolution aa and supply the
+AA topology and DCD as --PSF and --DCD.
+
+Examples
+--------
+CG — Q, G, K only:
+  python scripts/run_OP_on_simulation_traj.py \\
+    --Traj 420 --ID 1ZMR \\
+    --PSF  $REFSTRUCT/1zmr_model_clean_ca.psf \\
+    --COR  $REFSTRUCT/1zmr_model_clean_ca.cor \\
+    --DCD  $DATASTORE/cg_trajectories/420_prod.dcd \\
+    --sec_elements $REFSTRUCT/secondary_struc_defs.txt \\
+    --domain       $REFSTRUCT/domain_def.dat \\
+    --outdir $DATASTORE/outputs/OP_demo \\
+    --ops Q G K
+
+AA trajectory — SASA and XP only:
+  python scripts/run_OP_on_simulation_traj.py \\
+    --Traj 420 --ID 1ZMR \\
+    --PSF    $REFSTRUCT/1zmr_model_clean.pdb \\
+    --DCD    $DATASTORE/aa_trajectories/420_prod_aa.dcd \\
+    --resolution aa \\
+    --outdir $DATASTORE/outputs/OP_demo_AA \\
+    --ops SASA XP \\
+    --xp_pdb $REFSTRUCT/1zmr_model_clean.pdb
+
+Flags
+-----
+  --Traj                 Trajectory number (used in output filenames)
+  --ID                   Base name for output files
+  --PSF                  Topology file (CG PSF or AA PDB)
+  --DCD                  DCD trajectory
+  --outdir               Output directory (default: ./)
+  --start                First frame index, 0-based (default: 0)
+  --ops                  OPs to compute: Q G K SASA XP (default: Q G K)
+  --resolution           Trajectory resolution: cg (default) or aa
+  --contacts             Contact type: calpha or heavy (default: calpha for cg, heavy for aa)
+  --ent_detection_method ENT detection: 1=GLN, 2=TLN (default), 3=GLN+TLN same termini
+  --no_topoly            Disable topoly; use GLN-only workflow
+  --nproc                CPU cores for G calculation (default: 10)
+  --COR                  CG COR reference coordinates (required for Q, G, K)
+  --sec_elements         STRIDE secondary structure definitions (required for Q, G, K)
+  --domain               Domain boundary definitions (required for Q, G, K)
+  --xp_pdb               All-atom PDB for XP cross-link probability (required for XP)
+  --chunk_frames         Frames per chunk for Combined_GE (default: None = single file)
+  --chunk_suffix         Naming suffix for chunk files (default: _chunk)
+  --log_level            Logging verbosity: DEBUG, INFO, WARNING, ERROR (default: INFO)
+  --logdir               Directory for log file (default: same as --outdir)
+"""
+
+_CG_OPS  = {'Q', 'G', 'K'}
+_AA_OPS  = {'SASA', 'XP'}
+_ALL_OPS = _CG_OPS | _AA_OPS
+
+
+def main(argv=None):
+
+    ###---------------------------------------------------------------------------------------------------------
+    import sys, os
+    import argparse
+    import time
+    import logging
+    start_time = time.time()
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    parser = argparse.ArgumentParser(
+        description="Calculate order parameters on CG and/or all-atom trajectories.")
+    # --- identity / IO ---
+    parser.add_argument("--Traj",    type=str, required=True,  help="Trajectory number (used in output filenames)")
+    parser.add_argument("--ID",      type=str, required=True,  help="Base name for output files")
+    parser.add_argument("--PSF",     type=str, required=True,  help="Topology file (CG PSF or AA PDB)")
+    parser.add_argument("--DCD",     type=str, required=True,  help="DCD trajectory")
+    parser.add_argument("--outdir",  type=str, default='./',   help="Output directory (default: ./)")
+    parser.add_argument("--start",   type=int, default=0,      help="First frame index, 0-based (default: 0)")
+
+    # --- which OPs ---
+    parser.add_argument("--ops", nargs='+', default=['Q', 'G', 'K'], choices=['Q', 'G', 'K', 'SASA', 'XP'], help="Order parameters to compute (default: Q G K)")
+    
+    # --- trajectory settings ---
+    parser.add_argument("--resolution", choices=["cg", "aa"], default="cg", help="Trajectory resolution: cg (default) or aa")
+    parser.add_argument("--contacts",   choices=["calpha", "heavy"], default=None, help="Contact type: calpha or heavy (default: calpha for cg, heavy for aa)")
+    parser.add_argument("--ent_detection_method", type=int, default=1, help="ENT detection: 1=GLN, 2=TLN (default), 3=GLN+TLN same termini")
+    parser.add_argument("--no_topoly", action="store_true", help="Disable topoly crossing detection (uses GLN-only workflow)")
+    parser.add_argument("--nproc",  type=int, default=10, help="CPU cores for G (default: 10)")
+
+    # --- CG-specific inputs (required for Q/G/K) ---
+    parser.add_argument("--COR",          type=str, default=None, help="CG COR reference coordinates")
+    parser.add_argument("--sec_elements", type=str, default=None, help="STRIDE secondary structure definitions file")
+    parser.add_argument("--domain",       type=str, default=None, help="Domain boundary definitions file")
+
+    parser.add_argument("--xp_pdb",   type=str, default=None, help="All-atom PDB for XP (required for XP)")
+
+    # --- G chunking (for large trajectories) ---
+    parser.add_argument("--chunk_frames", type=int, default=None, help="Frames per chunk for Combined_GE output (default: None = single file)")
+    parser.add_argument("--chunk_suffix", type=str, default="_chunk", help="Naming suffix for chunked files (default: _chunk)")
+
+    # --- logging ---
+    parser.add_argument("--log_level", default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR"], help="Logging verbosity (default: INFO)")
+    parser.add_argument("--logdir", type=str, default=None, help="Directory for log file (default: same as --outdir)")
+    args = parser.parse_args(argv)
+
+    ops = set(args.ops)
+    traj   = args.Traj
+    ID     = args.ID
+    outdir = args.outdir
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    # --- resolve derived settings ---
+    contacts = args.contacts if args.contacts is not None else ("calpha" if args.resolution == "cg" else "heavy")
+    Calpha   = contacts == "calpha"
+    CG       = args.resolution == "cg"
+    topoly   = not args.no_topoly
+
+    log_level = getattr(logging, args.log_level.upper(), logging.INFO)
+    log_id    = f"{ID}_Traj{traj}"
+    logdir    = args.logdir if args.logdir is not None else outdir
+
+    # Pre-configure all EntDetect loggers so they share one log file
+    logger = setup_logger('run_OP', outdir=logdir, ID=log_id, log_level=log_level)
+    for _cls in ['CalculateOP', 'GaussianEntanglement']:
+        setup_logger(_cls, outdir=logdir, ID=log_id, log_level=log_level)
+    logger.info(f'args: {args}')
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    # --- input validation ---
+    if ops & _CG_OPS and not all([args.COR, args.sec_elements, args.domain]):
+        parser.error("--COR, --sec_elements, and --domain are required when computing Q, G, or K.")
+
+    if ops & _AA_OPS:
+        if CG:
+            parser.error("SASA and XP require an all-atom trajectory: set --resolution aa.")
+        if 'XP' in ops and args.xp_pdb is None:
+            parser.error("--xp_pdb is required when XP is in --ops.")
+    ###---------------------------------------------------------------------------------------------------------
+
+    ###---------------------------------------------------------------------------------------------------------
+    # --- instantiate CalculateOP for primary (CG or AA) trajectory ---
+    CalcOP = CalculateOP(outdir=outdir,
+                            Traj=traj,
+                            ID=ID,
+                            psf=args.PSF,
+                            cor=args.COR,
+                            sec_elements=args.sec_elements,
+                            dcd=args.DCD,
+                            domain=args.domain,
+                            start=args.start,
+                            ent_detection_method=args.ent_detection_method,
+                            log_level=log_level,
+                            logdir=logdir)
+    logger.info(f'CalculateOP (primary): {CalcOP}')
+
+    if 'Q' in ops:
+        Qdata_dict = CalcOP.Q()
+        logger.info(f'Q keys: {list(Qdata_dict.keys())}')
+
+    if 'G' in ops:
+        Gdata_dict = CalcOP.G(topoly=topoly, Calpha=Calpha, CG=CG, nproc=args.nproc, chunk_frames=args.chunk_frames, chunk_suffix=args.chunk_suffix)
+        logger.info(f'G keys: {list(Gdata_dict.keys())}')
+
+    if 'K' in ops:
+        Kdata_dict = CalcOP.K()
+        logger.info(f'K keys: {list(Kdata_dict.keys())}')
+
+    if 'SASA' in ops:
+        SASAdata_dict = CalcOP.SASA()
+        logger.info(f'SASA keys: {list(SASAdata_dict.keys())}')
+
+    if 'XP' in ops:
+        XPdata_dict = CalcOP.XP(pdb=args.xp_pdb, use_traj=True, nproc=args.nproc)
+        logger.info(f'XP keys: {list(XPdata_dict.keys())}')
+    ###---------------------------------------------------------------------------------------------------------
+
+    logger.info(f'NORMAL TERMINATION - {time.time() - start_time:.1f} seconds')
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())