Skip to content

HmsCmdr

HEC-HMS simulation execution engine.

hms_commander.HmsCmdr

HmsCmdr - HEC-HMS Simulation Execution Engine

This module provides static methods for executing HEC-HMS simulations. It mirrors the RasCmdr pattern from ras-commander.

Execution is performed via Jython scripts using the HmsJython class.

All methods are static and designed to be used without instantiation.

HmsCmdr

HEC-HMS simulation execution - mirrors RasCmdr pattern.

All static methods, no instantiation required.

Example

from hms_commander import HmsCmdr, init_hms_project init_hms_project(r"C:/HMS_Projects/MyProject", hms_exe_path=r"C:/HEC/HEC-HMS/4.9/hec-hms.cmd") success = HmsCmdr.compute_run("Run 1") results = HmsCmdr.compute_parallel(["Run 1", "Run 2", "Run 3"])

Source code in hms_commander/HmsCmdr.py
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
class HmsCmdr:
    """
    HEC-HMS simulation execution - mirrors RasCmdr pattern.

    All static methods, no instantiation required.

    Example:
        >>> from hms_commander import HmsCmdr, init_hms_project
        >>> init_hms_project(r"C:/HMS_Projects/MyProject", hms_exe_path=r"C:/HEC/HEC-HMS/4.9/hec-hms.cmd")
        >>> success = HmsCmdr.compute_run("Run 1")
        >>> results = HmsCmdr.compute_parallel(["Run 1", "Run 2", "Run 3"])
    """

    @staticmethod
    @log_call
    def compute_run(
        run_name: str,
        hms_object=None,
        dest_folder: Optional[Union[str, Path]] = None,
        overwrite_dest: bool = False,
        timeout: int = DEFAULT_EXECUTION_TIMEOUT,
        save_project: bool = True,
        max_memory: str = None,
        initial_memory: str = None,
        additional_java_opts: Optional[List[str]] = None
    ) -> bool:
        """
        Execute a single HEC-HMS simulation run.

        Args:
            run_name: Name of the simulation run to execute
            hms_object: Optional HmsPrj instance (uses global hms if None)
            dest_folder: Optional destination folder for execution
                        (copies project there first)
            overwrite_dest: Whether to overwrite existing destination
            timeout: Seconds for the whole call: waiting for another compute
                on the same ``dest_folder`` or output files, and running HEC-HMS
                (which gets only the time left after any wait)
            save_project: Whether to save project after computation
            max_memory: Maximum JVM heap size (default: "4G")
                       Examples: "4G", "8G", "16G" for large models
            initial_memory: Initial JVM heap size (default: "128M")
            additional_java_opts: Extra JVM options
                       Examples: ["-XX:+UseG1GC", "-XX:MaxGCPauseMillis=200"]

        Returns:
            True only if HEC-HMS computed the run in this call. The log file
            and results DSS file are those the run's ``.run`` entry names
            (``Log File:``, ``DSS File:``). Both files (and ``dest_folder``,
            if given) are locked across threads and processes from before
            launch until verification ends, so another compute cannot write
            them meanwhile; computes on other files are not held up. Before
            launch, an existing log is moved to a backup name unique to this
            call, ``<log name>.hms-commander-prev-<32 hex>`` (deleted
            afterwards if the run wrote a new log, moved back if not), and
            the DSS file's size, modification time and hash (up to 512 MB)
            are recorded. Then:

            - the generated script reported no error;
            - a run log exists (written while this call held the lock) and
              has a section for this run (``NOTE 15301 ... "<run_name>"``)
              with the "Finished computing" note for it (NOTE 15302), no
              ERROR line and no "Aborted run" warning (WARNING 15303);
            - the results DSS file is new, or its size, modification time or
              content hash changed.

            Nothing is compared with the clock. If the run, its ``Log File:``
            or its ``DSS File:`` entry cannot be found, the run cannot be
            verified and False is returned. False otherwise as well; the
            reason and the relevant log lines are logged at ERROR level.

        Raises:
            RuntimeError: If the project is not initialized, or if no
                ``hms_exe_path`` was given and no installed HEC-HMS suits the
                project's ``Version:`` (equal, a newer patch of the same
                major.minor, or a newer major.minor), or if that ``Version:``
                is not a comparable version. An older HEC-HMS is never chosen
                automatically. Also if this thread is already computing with
                the same output files (a nested call).
            TimeoutError: If another compute holds the run's output files
                (or ``dest_folder``) until ``timeout`` runs out, or no time is
                left to run HEC-HMS once they are free. ``timeout`` is one
                budget for waiting and running; HEC-HMS gets only what is
                left after any wait.

        Note:
            Without ``hms_exe_path``, the HEC-HMS version is chosen from the
            project's ``.hms`` file ``Version:`` line; see
            :meth:`HmsJython.find_hms_executable`.

        Example:
            >>> from hms_commander import HmsCmdr, init_hms_project
            >>> init_hms_project(r"C:/Projects/MyProject", hms_exe_path=r"C:/HEC/HEC-HMS/4.9/hec-hms.cmd")
            >>> success = HmsCmdr.compute_run("Run 1")
            >>> # For large models:
            >>> success = HmsCmdr.compute_run("Run 1", max_memory="16G")
        """
        from .HmsPrj import hms
        hms_obj = hms_object or hms

        if hms_obj is None or not hms_obj.initialized:
            raise RuntimeError("HMS project not initialized. Call init_hms_project() first.")

        HmsCmdr._ensure_hms_executable(hms_obj)

        # One budget for the whole call: waiting for locks and running HEC-HMS.
        deadline = time.monotonic() + timeout

        # A copied destination folder is locked while it is filled and
        # computed, so a concurrent call cannot replace it meanwhile.
        dest_lock = (
            OutputLock([Path(dest_folder)], deadline, purpose=f"copy for run '{run_name}'")
            if dest_folder else contextlib.nullcontext()
        )
        with dest_lock:
            # Determine working directory
            if dest_folder:
                dest_folder = Path(dest_folder)
                working_project = HmsCmdr._copy_project(
                    hms_obj.project_folder,
                    dest_folder,
                    overwrite_dest
                )
            else:
                working_project = hms_obj.project_folder

            logger.info(f"Computing run '{run_name}' in {working_project}")

            # Generate script
            script = HmsJython.generate_compute_script(
                project_path=working_project,
                run_name=run_name,
                save_project=save_project
            )

            # Execute
            success, stdout, stderr = HmsCmdr._execute_and_verify(
                run_name, working_project, script,
                hms_exe_path=hms_obj.hms_exe_path,
                timeout=timeout,
                max_memory=max_memory,
                initial_memory=initial_memory,
                additional_java_opts=additional_java_opts,
                deadline=deadline,
            )

        if success:
            logger.info(f"Run '{run_name}' completed successfully")
        else:
            logger.error(
                f"Run '{run_name}' failed. "
                f"See: https://hms-commander.readthedocs.io/user-guide/execution/"
            )
            if stderr:
                logger.error(f"Error output: {stderr}")

        return success

    @staticmethod
    @log_call
    def compute_parallel(
        run_names: Optional[List[str]] = None,
        max_workers: int = 2,
        hms_object=None,
        dest_folder: Optional[Union[str, Path]] = None,
        timeout_per_run: int = DEFAULT_EXECUTION_TIMEOUT,
        max_memory: str = None,
        initial_memory: str = None,
        additional_java_opts: Optional[List[str]] = None
    ) -> Dict[str, bool]:
        """
        Execute multiple HEC-HMS runs in parallel using worker folders.

        Each run is executed in a separate copy of the project to avoid
        conflicts. This is the recommended method for batch processing.

        Args:
            run_names: List of run names to execute (all runs if None)
            max_workers: Maximum number of parallel workers
            hms_object: Optional HmsPrj instance
            dest_folder: Base folder for worker copies
            timeout_per_run: Seconds for each run, from when it gets a worker
                folder: waiting for another compute on the same folder or
                output files, and running HEC-HMS
            max_memory: Maximum JVM heap size (default: "4G")
            initial_memory: Initial JVM heap size (default: "128M")
            additional_java_opts: Extra JVM options

        Returns:
            Dictionary mapping run names to success status.
            Each run is verified as in :meth:`compute_run` (run log section
            for that run, changed results DSS, compared with a pre-launch
            record). If no ``hms_exe_path`` is set, the HEC-HMS version is
            chosen as in :meth:`compute_run`; RuntimeError is raised when no
            installation suits the project's ``Version:``.
            A run whose worker folder or output files another compute holds
            until ``timeout_per_run`` runs out is reported as False, with the
            ``TimeoutError`` logged; the other runs continue.

        Example:
            >>> results = HmsCmdr.compute_parallel(
            ...     ["Run 1", "Run 2", "Run 3"],
            ...     max_workers=3
            ... )
            >>> for run, success in results.items():
            ...     print(f"{run}: {'OK' if success else 'FAILED'}")
        """
        from .HmsPrj import hms
        hms_obj = hms_object or hms

        if hms_obj is None or not hms_obj.initialized:
            raise RuntimeError("HMS project not initialized")

        # Get run names if not specified
        if run_names is None:
            if hms_obj.run_df.empty:
                raise ValueError("No runs found in project")
            run_names = hms_obj.run_df['name'].tolist()

        if not run_names:
            logger.warning("No runs to execute")
            return {}

        HmsCmdr._ensure_hms_executable(hms_obj)

        # Set up destination folder
        if dest_folder:
            base_dest = Path(dest_folder)
        else:
            base_dest = hms_obj.project_folder.parent / f"{hms_obj.project_name}_workers"

        base_dest.mkdir(parents=True, exist_ok=True)

        logger.info(f"Starting parallel execution of {len(run_names)} runs with {max_workers} workers")
        results = {}

        # Each running task takes a free worker folder and returns it when
        # done, so no two runs ever use the same folder at once.
        free_workers: "queue.Queue[int]" = queue.Queue()
        for worker_id in range(max_workers):
            free_workers.put(worker_id)

        def execute_worker(run_name: str) -> Tuple[str, bool]:
            """Execute a single run in a free worker folder."""
            worker_id = free_workers.get()
            worker_folder = base_dest / f"worker_{worker_id}"
            # The run's budget (lock waits and execution) starts once it has
            # a worker folder.
            deadline = time.monotonic() + timeout_per_run

            try:
                # The worker folder is also locked across processes, in case
                # another call uses the same dest_folder.
                with OutputLock([worker_folder], deadline,
                                purpose=f"worker for run '{run_name}'"):
                    # Copy project to worker folder
                    working_project = HmsCmdr._copy_project(
                        hms_obj.project_folder,
                        worker_folder,
                        overwrite=True
                    )

                    # Generate and execute script
                    script = HmsJython.generate_compute_script(
                        project_path=working_project,
                        run_name=run_name,
                        save_project=True
                    )

                    success, stdout, stderr = HmsCmdr._execute_and_verify(
                        run_name, working_project, script,
                        hms_exe_path=hms_obj.hms_exe_path,
                        timeout=timeout_per_run,
                        max_memory=max_memory,
                        initial_memory=initial_memory,
                        additional_java_opts=additional_java_opts,
                        deadline=deadline,
                    )
                return run_name, success

            except Exception as e:
                logger.error(f"Worker {worker_id} failed for '{run_name}': {e}")
                return run_name, False
            finally:
                free_workers.put(worker_id)

        # Execute in parallel
        with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
            futures = {}
            for run_name in run_names:
                future = executor.submit(execute_worker, run_name)
                futures[future] = run_name

            for future in concurrent.futures.as_completed(futures):
                run_name, success = future.result()
                results[run_name] = success
                status = "completed" if success else "FAILED"
                logger.info(f"Run '{run_name}' {status}")

        # Summary
        successful = sum(1 for s in results.values() if s)
        failed = len(results) - successful
        logger.info(f"Parallel execution complete: {successful} succeeded, {failed} failed")

        return results

    @staticmethod
    @log_call
    def compute_batch(
        run_names: List[str],
        hms_object=None,
        save_after_each: bool = False,
        timeout: int = 7200,
        max_memory: str = None,
        initial_memory: str = None,
        additional_java_opts: Optional[List[str]] = None
    ) -> Dict[str, bool]:
        """
        Execute multiple runs sequentially in a single HMS session.

        This is more efficient than compute_parallel when runs don't conflict
        and don't need separate output files. Runs that share a run log are
        computed one HMS session per run instead (see Returns).

        Args:
            run_names: List of run names to execute
            hms_object: Optional HmsPrj instance
            save_after_each: Whether to save project after each run
            timeout: Seconds for the whole batch: every wait for another
                compute on the same output files and every HEC-HMS session
            max_memory: Maximum JVM heap size (default: "4G")
            initial_memory: Initial JVM heap size (default: "128M")
            additional_java_opts: Extra JVM options

        Returns:
            Dictionary mapping run names to success status.
            Each run is verified as in :meth:`compute_run` (run log section
            for that run, changed results DSS, compared with a pre-launch
            record). If no ``hms_exe_path`` is set, the HEC-HMS version is
            chosen as in :meth:`compute_run`; RuntimeError is raised when no
            installation suits the project's ``Version:``.
            When runs share a ``Log File:``, HEC-HMS would keep only the last
            run's section in one session, so each run is computed in its own
            HEC-HMS session, in the given order, and verified before the next
            starts. ``timeout`` then covers all of these sessions together.
            Runs that share a ``DSS File:`` cannot tell from the DSS file
            which of them wrote it, so the log decides.

        Raises:
            RuntimeError: If the project is not initialized, or no
                installation suits the project's ``Version:``.
            TimeoutError: If another compute holds the runs' output files
                until ``timeout`` runs out, or no time is left to run HEC-HMS
                once they are free. With per-run sessions, runs completed
                before that are not reported; a run reached after the budget is
                used up without waiting is reported as False.

        Example:
            >>> results = HmsCmdr.compute_batch(["Run 1", "Run 2", "Run 3"])
        """
        from .HmsPrj import hms
        hms_obj = hms_object or hms

        if hms_obj is None or not hms_obj.initialized:
            raise RuntimeError("HMS project not initialized")

        if not run_names:
            logger.warning("No runs to execute")
            return {}

        HmsCmdr._ensure_hms_executable(hms_obj)

        logger.info(f"Starting batch execution of {len(run_names)} runs")

        project_folder = hms_obj.project_folder
        # One budget for the whole batch: lock waits and every HEC-HMS session.
        deadline = time.monotonic() + timeout
        shared = HmsCmdr._shared_log_runs(project_folder, run_names)
        results: Dict[str, bool] = {}

        if shared:
            # HEC-HMS rewrites a run log for every run it computes, so in one
            # session a shared log keeps only the last run's section. Compute
            # each run in its own session, in the given order, and verify it
            # before the next run can overwrite its log.
            for names in shared.values():
                logger.info(
                    f"Runs {', '.join(repr(n) for n in names)} write the same run log; "
                    "computing each run in its own HEC-HMS session so that each "
                    "can be verified before the next."
                )
            for run_name in run_names:
                if remaining(deadline) <= 0:
                    logger.error(
                        f"Run '{run_name}' not computed: the batch timeout of "
                        f"{timeout} s was used up by earlier runs."
                    )
                    results[run_name] = False
                    continue
                script = HmsJython.generate_batch_compute_script(
                    project_path=project_folder,
                    run_names=[run_name],
                    save_after_each=save_after_each
                )
                verified, stdout, _ = HmsCmdr._execute_and_verify(
                    run_name, project_folder, script,
                    hms_exe_path=hms_obj.hms_exe_path,
                    timeout=timeout,
                    max_memory=max_memory,
                    initial_memory=initial_memory,
                    additional_java_opts=additional_java_opts,
                    deadline=deadline,
                )
                results[run_name] = verified
        else:
            # Generate batch script
            script = HmsJython.generate_batch_compute_script(
                project_path=project_folder,
                run_names=run_names,
                save_after_each=save_after_each
            )
            # Lock every run's outputs for the whole session, so no other
            # compute can write them between snapshot and verification.
            outputs = []
            for name in run_names:
                outputs.extend(HmsCmdr._run_output_files(project_folder, name)[:2])
            with OutputLock(outputs, deadline, purpose=f"batch in {Path(project_folder).name}"):
                snapshots = {
                    name: HmsCmdr._snapshot_run(project_folder, name)
                    for name in run_names
                }
                session_budget = remaining(deadline)
                if session_budget <= 0:
                    for snapshot in snapshots.values():
                        HmsCmdr._release_snapshot(snapshot)
                    raise TimeoutError(
                        "Batch not started: its time budget was used up waiting for "
                        "other computes on the same files."
                    )

                # Execute
                try:
                    success, stdout, stderr = HmsJython.execute_script(
                        script_content=script,
                        hms_exe_path=hms_obj.hms_exe_path,
                        working_dir=project_folder,
                        timeout=session_budget,
                        max_memory=max_memory,
                        initial_memory=initial_memory,
                        additional_java_opts=additional_java_opts
                    )
                except BaseException:
                    for snapshot in snapshots.values():
                        HmsCmdr._release_snapshot(snapshot)
                    raise

                for run_name in run_names:
                    # Default to overall success status
                    status = success

                    # Try to parse individual status from output
                    if stdout:
                        if f"Completed: {run_name}" in stdout:
                            status = True
                        elif f"Error computing {run_name}" in stdout:
                            status = False

                    # Confirm each run from its own run log and results DSS
                    results[run_name] = HmsCmdr._verify_run(status, snapshots[run_name])

        # Summary
        successful = sum(1 for s in results.values() if s)
        failed = len(results) - successful
        logger.info(f"Batch execution complete: {successful} succeeded, {failed} failed")

        return results

    @staticmethod
    @log_call
    def compute_with_parameters(
        run_name: str,
        basin_name: str,
        parameter_modifications: Dict[str, Dict[str, Any]],
        hms_object=None,
        dest_folder: Optional[Union[str, Path]] = None,
        timeout: int = DEFAULT_EXECUTION_TIMEOUT,
        max_memory: str = None,
        initial_memory: str = None,
        additional_java_opts: Optional[List[str]] = None
    ) -> Tuple[bool, Path]:
        """
        Execute a run with modified parameters.

        Useful for sensitivity analysis and calibration workflows.

        Args:
            run_name: Name of the simulation run
            basin_name: Name of the basin model to modify
            parameter_modifications: Dictionary of element -> parameter changes
            hms_object: Optional HmsPrj instance
            dest_folder: Destination for modified project
            timeout: Seconds for the whole call: waiting for another compute
                on the same destination or output files, and running HEC-HMS
                (which gets only the time left after any wait)
            max_memory: Maximum JVM heap size (default: "4G")
            initial_memory: Initial JVM heap size (default: "128M")
            additional_java_opts: Extra JVM options

        Returns:
            Tuple of (success, path to output folder).
            Each run is verified as in :meth:`compute_run` (run log section
            for that run, changed results DSS, compared with a pre-launch
            record). If no ``hms_exe_path`` is set, the HEC-HMS version is
            chosen as in :meth:`compute_run`; RuntimeError is raised when no
            installation suits the project's ``Version:``.

        Raises:
            RuntimeError: If the project is not initialized, or no
                installation suits the project's ``Version:``.
            TimeoutError: If another compute holds ``dest_folder`` or the run's
                output files until ``timeout`` runs out, or no time is left to
                run HEC-HMS once they are free.

        Example:
            >>> mods = {
            ...     "Subbasin-1": {"CurveNumber": 80, "InitialAbstraction": 0.5},
            ...     "Subbasin-2": {"CurveNumber": 75}
            ... }
            >>> success, output_path = HmsCmdr.compute_with_parameters(
            ...     "Run 1", "Basin 1", mods
            ... )
        """
        from .HmsPrj import hms
        hms_obj = hms_object or hms

        if hms_obj is None or not hms_obj.initialized:
            raise RuntimeError("HMS project not initialized")

        HmsCmdr._ensure_hms_executable(hms_obj)

        # Set up destination folder
        if dest_folder:
            dest_folder = Path(dest_folder)
        else:
            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
            dest_folder = hms_obj.project_folder.parent / f"{hms_obj.project_name}_modified_{timestamp}"

        # The destination is locked while it is filled and computed, so a
        # concurrent call with the same dest_folder waits instead of
        # replacing it.
        # One budget for the whole call: waiting for locks and running HEC-HMS.
        deadline = time.monotonic() + timeout
        with OutputLock([dest_folder], deadline, purpose=f"copy for run '{run_name}'"):
            # Copy project
            working_project = HmsCmdr._copy_project(
                hms_obj.project_folder,
                dest_folder,
                overwrite=True
            )

            logger.info(f"Computing '{run_name}' with modified parameters in {working_project}")

            # Generate script with modifications
            script = HmsJython.generate_parameter_modification_script(
                project_path=working_project,
                basin_name=basin_name,
                modifications=parameter_modifications,
                run_name=run_name
            )

            # Execute
            success, stdout, stderr = HmsCmdr._execute_and_verify(
                run_name, working_project, script,
                hms_exe_path=hms_obj.hms_exe_path,
                timeout=timeout,
                max_memory=max_memory,
                initial_memory=initial_memory,
                additional_java_opts=additional_java_opts,
                deadline=deadline,
            )

        if success:
            logger.info(f"Modified run '{run_name}' completed successfully")
        else:
            logger.error(f"Modified run '{run_name}' failed")

        return success, working_project

    @staticmethod
    @log_call
    def verify_hms_installation(
        hms_exe_path: Optional[Union[str, Path]] = None
    ) -> Dict[str, Any]:
        """
        Verify HEC-HMS installation and return information.

        Args:
            hms_exe_path: Path to HEC-HMS executable (auto-detect if None)

        Returns:
            Dictionary with installation information
        """
        result = {
            'found': False,
            'executable': None,
            'version': None,
            'java_home': os.environ.get('JAVA_HOME'),
            'hec_hms_home': os.environ.get('HEC_HMS_HOME')
        }

        if hms_exe_path:
            exe_path = Path(hms_exe_path)
        else:
            exe_path = HmsJython.find_hms_executable()

        if exe_path and exe_path.exists():
            result['found'] = True
            result['executable'] = str(exe_path)

            # Try to extract version from path
            path_parts = exe_path.parts
            for part in path_parts:
                if part.replace('.', '').isdigit() or (
                    len(part) > 2 and part[0].isdigit() and '.' in part
                ):
                    result['version'] = part
                    break

        return result

    # =========================================================================
    # Private helper methods
    # =========================================================================

    @staticmethod
    def _ensure_hms_executable(hms_obj, search_paths=None, include_defaults=True) -> Path:
        """
        Set ``hms_obj.hms_exe_path`` from the project's version when it is unset.

        The project's ``.hms`` ``Version:`` line selects the installation (see
        :meth:`HmsJython.find_hms_executable`). An explicitly given path is
        kept; a warning is logged when its version is older than the project's.

        Raises:
            RuntimeError: If no suitable installation is found.
        """
        project_version = getattr(hms_obj, "hms_version", None)
        if project_version in (None, "", "Unknown"):
            project_version = None

        if hms_obj.hms_exe_path is not None:
            exe = Path(hms_obj.hms_exe_path)
            # A folder name such as "4.13" has a suffix, so test for a file
            install = exe.parent if exe.is_file() else exe
            installed = HmsJython._parse_version_text(install.name)
            wanted = HmsJython._parse_version_text(project_version)
            if installed and wanted and installed < wanted:
                logger.warning(
                    f"hms_exe_path selects HEC-HMS {install.name}, older than the "
                    f"project's version {project_version}. HEC-HMS may abort the run."
                )
            return exe

        if project_version is None:
            logger.warning(
                "The project's .hms file declares no Version; using the newest "
                "installed HEC-HMS."
            )

        hms_exe = HmsJython.find_hms_executable(
            version=project_version,
            search_paths=search_paths,
            include_defaults=include_defaults,
        )
        if hms_exe is None and project_version is not None and (
            HmsJython._parse_version_text(project_version) is None
        ):
            raise RuntimeError(
                f"The project's Version '{project_version}' is not a version "
                "format hms-commander can compare (expected numbers such as 4.13 "
                "or 4.7.1, optionally with an alpha, beta or rc suffix such as "
                "4.13-beta2 or 4.13-rc10), and no "
                "installation has that exact name. Pass hms_exe_path to "
                "init_hms_project() to choose one explicitly."
            )
        if hms_exe is None:
            installed = ", ".join(
                HmsJython._installed_hms_versions(search_paths, include_defaults)
            ) or "none"
            raise RuntimeError(
                f"No installed HEC-HMS suits this project (project Version: "
                f"{project_version or 'not declared'}; installed: {installed}). "
                "Install that version, or pass hms_exe_path to init_hms_project() "
                "to choose one explicitly."
            )
        logger.info(
            f"Using HEC-HMS {hms_exe.name} for project version {project_version}"
        )
        hms_obj.hms_exe_path = hms_exe
        return hms_exe

    @staticmethod
    def _run_output_files(project_folder: Union[str, Path], run_name: str) -> Tuple[Optional[Path], Optional[Path], str]:
        """
        Read the run log and results DSS paths of ``run_name`` from the project's .run files.

        The .run files in ``project_folder`` are read when called, so a
        working copy or an edited run is described as it is now. No default
        name is guessed: every run in the HEC-HMS 4.4.1 to 4.13 sample
        projects declares both ``Log File:`` and ``DSS File:``.

        Returns:
            Tuple of (log path or None, DSS path or None, problem). ``problem``
            is an empty string when both paths were found, otherwise the reason.
        """
        from ._parsing import HmsFileParser

        project_folder = Path(project_folder)
        entry = None
        for run_file in sorted(project_folder.glob("*.run")):
            try:
                blocks = HmsFileParser.parse_blocks(
                    HmsFileParser.read_file(run_file), "Run"
                )
            except Exception as e:  # unreadable .run file
                logger.debug(f"Could not read {run_file.name}: {e}")
                continue
            if run_name in blocks:
                entry = blocks[run_name]
                break
        if entry is None:
            return None, None, f"run '{run_name}' is not defined in a .run file in the project"

        log_name = str(entry.get("Log File", "") or "").strip()
        dss_name = str(entry.get("DSS File", "") or "").strip()
        log_path = project_folder / log_name if log_name else None
        dss_path = project_folder / dss_name if dss_name else None
        missing = [label for label, value in (("Log File", log_name), ("DSS File", dss_name)) if not value]
        problem = (
            f"run '{run_name}' declares no {' or '.join(missing)} entry, so its "
            "output cannot be verified" if missing else ""
        )
        return log_path, dss_path, problem

    @staticmethod
    def _execute_and_verify(
        run_name: str,
        project_folder: Union[str, Path],
        script: str,
        hms_exe_path: Union[str, Path],
        timeout: int = DEFAULT_EXECUTION_TIMEOUT,
        max_memory: str = None,
        initial_memory: str = None,
        additional_java_opts: Optional[List[str]] = None,
        deadline: Optional[float] = None,
    ) -> Tuple[bool, str, str]:
        """
        Lock one run's outputs, snapshot them, execute ``script`` in
        ``project_folder``, verify the run, and release.

        The run's log and results DSS file are locked (:class:`OutputLock`)
        across threads and processes from before the snapshot until
        verification and clean-up are done, so another compute cannot write
        them in between and have its outputs credited to this run. Computes
        on other output files are not blocked.

        One budget covers waiting and running: ``deadline`` (a
        ``time.monotonic()`` value; default ``now + timeout``) bounds the
        lock wait, and HEC-HMS is then given only the time left before it.

        Returns:
            Tuple of (verified success, stdout, stderr). If execution raises,
            the prior run log is put back before the exception propagates.

        Raises:
            TimeoutError: If the outputs cannot be locked before the
                deadline, or no time is left to run HEC-HMS once they are.
        """
        if deadline is None:
            deadline = time.monotonic() + timeout
        log_path, dss_path, _ = HmsCmdr._run_output_files(project_folder, run_name)
        with OutputLock([log_path, dss_path], deadline,
                        purpose=f"run '{run_name}' in {Path(project_folder).name}"):
            snapshot = HmsCmdr._snapshot_run(project_folder, run_name)
            run_budget = remaining(deadline)
            if run_budget <= 0:
                HmsCmdr._release_snapshot(snapshot)
                raise TimeoutError(
                    f"Run '{run_name}' not started: its time budget was used up "
                    "waiting for other computes on the same files."
                )
            try:
                success, stdout, stderr = HmsJython.execute_script(
                    script_content=script,
                    hms_exe_path=hms_exe_path,
                    working_dir=project_folder,
                    timeout=run_budget,
                    max_memory=max_memory,
                    initial_memory=initial_memory,
                    additional_java_opts=additional_java_opts,
                )
            except BaseException:
                HmsCmdr._release_snapshot(snapshot)
                raise
            return HmsCmdr._verify_run(success, snapshot, stdout), stdout, stderr

    @staticmethod
    def _file_state(path: Optional[Path], hash_limit: int) -> Dict[str, Any]:
        """Size, mtime_ns and SHA-256 (up to ``hash_limit`` bytes) of a file; ``exists`` False if absent."""
        state: Dict[str, Any] = {"path": path, "exists": False}
        if path is None or not path.exists():
            return state
        stat = path.stat()
        state.update(exists=True, size=stat.st_size, mtime_ns=stat.st_mtime_ns)
        if stat.st_size <= hash_limit:
            digest = hashlib.sha256()
            with open(path, "rb") as f:
                for chunk in iter(lambda: f.read(1024 * 1024), b""):
                    digest.update(chunk)
            state["sha256"] = digest.hexdigest()
        return state

    @staticmethod
    def _log_backups(log_path: Path) -> List[Path]:
        """HMS Commander backups of ``log_path`` (``<log>.hms-commander-prev-<32 hex>``), oldest name first."""
        pattern = re.compile(re.escape(log_path.name + _LOG_BACKUP_INFIX) + r"[0-9a-f]{32}$")
        try:
            return sorted(p for p in log_path.parent.iterdir() if pattern.match(p.name))
        except OSError:
            return []

    @staticmethod
    def _recover_orphan_backups(log_path: Path) -> List[Path]:
        """
        Deal with backups that an interrupted compute left beside ``log_path``.

        Called with the run's outputs locked, so any backup found belongs to
        a compute that ended without cleaning up (for example, a killed
        Python process). A backup is never read as evidence of a run.

        - If the run log is missing and there is exactly one backup, the
          interrupted compute wrote no new log, so the backup is the user's
          earlier log: it is moved back to the log name.
        - Otherwise (a current log exists, which may be the interrupted run's
          own log, or several backups exist) nothing is moved or deleted.
          The backups are kept and listed in a warning for the user to
          review or delete.

        Returns:
            The backups that remain.
        """
        orphans = HmsCmdr._log_backups(log_path)
        if not orphans:
            return []
        if not log_path.exists() and len(orphans) == 1:
            try:
                move_no_replace(orphans[0], log_path)
                logger.warning(
                    f"Restored {log_path.name} from {orphans[0].name}, left by an "
                    "interrupted compute that wrote no new log."
                )
                return []
            except OSError as e:
                logger.warning(f"Could not restore {log_path.name} from {orphans[0].name}: {e}")
                return orphans
        logger.warning(
            f"Kept {len(orphans)} backup(s) of {log_path.name} left by interrupted "
            f"computes: {', '.join(p.name for p in orphans)}. They are not used as "
            "evidence; review or delete them."
        )
        return orphans

    @staticmethod
    def _snapshot_run(project_folder: Union[str, Path], run_name: str) -> Dict[str, Any]:
        """
        Prepare the run's outputs for verification, just before HEC-HMS starts.

        Call with the run's outputs locked (see :meth:`_execute_and_verify`).

        - Backups left by an interrupted compute are recovered or kept, as
          described in :meth:`_recover_orphan_backups`.
        - The prior run log, if any, is moved to
          ``<log name>.hms-commander-prev-<32 hex>``, a new name unique to
          this call; an existing file is never replaced. Any run log present
          after the run was therefore written while this call held the lock,
          even if its bytes equal the prior log's. :meth:`_release_snapshot`
          later deletes that backup if a new log was written, or moves it
          back if not.
        - The results DSS file's size, mtime_ns and SHA-256 (files up to
          512 MB) are recorded.

        :meth:`_verify_run` compares the files after the run with this
        record; no wall-clock time is compared with file times.
        """
        log_path, dss_path, problem = HmsCmdr._run_output_files(project_folder, run_name)
        snapshot: Dict[str, Any] = {
            "run_name": run_name, "problem": problem,
            "log_path": log_path, "log_backup": None,
            "dss": {"path": dss_path, "exists": False},
        }
        if problem:
            return snapshot
        try:
            HmsCmdr._recover_orphan_backups(log_path)
            snapshot["dss"] = HmsCmdr._file_state(dss_path, _DSS_HASH_LIMIT_BYTES)
            if log_path.exists():
                backup = log_path.with_name(log_path.name + _LOG_BACKUP_INFIX + uuid.uuid4().hex)
                move_no_replace(log_path, backup)
                snapshot["log_backup"] = backup
        except OSError as e:
            snapshot["problem"] = f"could not prepare the run outputs before the run: {e}"
        return snapshot

    @staticmethod
    def _release_snapshot(snapshot: Dict[str, Any]) -> None:
        """
        Deal with the prior run log that this call's :meth:`_snapshot_run` moved aside.

        Only the backup this call created is touched. If the run wrote a new
        log, the backup is deleted, as HEC-HMS replaces a run log when it
        computes the run. Otherwise the prior log is moved back. Safe to call
        more than once.
        """
        backup = snapshot.get("log_backup")
        if backup is None:
            return
        snapshot["log_backup"] = None
        log_path = snapshot["log_path"]
        try:
            if log_path.exists():
                backup.unlink(missing_ok=True)
            elif backup.exists():
                move_no_replace(backup, log_path)
        except OSError as e:
            logger.warning(f"Could not tidy the prior run log {backup.name}: {e}")

    @staticmethod
    def _shared_log_runs(project_folder: Union[str, Path], run_names: List[str]) -> Dict[str, List[str]]:
        """Group ``run_names`` that write the same run log file (two or more per group)."""
        groups: Dict[str, List[str]] = {}
        for name in run_names:
            log_path, _, _ = HmsCmdr._run_output_files(project_folder, name)
            if log_path is not None:
                groups.setdefault(str(log_path).lower(), []).append(name)
        return {key: names for key, names in groups.items() if len(names) > 1}

    @staticmethod
    def _read_log_text(path: Path) -> str:
        data = path.read_bytes()
        try:
            return data.decode("utf-8")
        except UnicodeDecodeError:
            return data.decode("latin-1")

    @staticmethod
    def _check_run_log(log_text: str, run_name: str) -> Tuple[bool, str, List[str]]:
        """
        Judge the section of a HEC-HMS run log that belongs to ``run_name``.

        The section starts at the last "Began computing simulation run
        "<run_name>"" note (NOTE 15301) and ends at the next NOTE 15301 of any
        run, so another run's result in the same log is never credited to
        ``run_name``. The run succeeded when that section has the "Finished
        computing" note for ``run_name`` (NOTE 15302), no "Aborted run"
        warning (WARNING 15303) and no ERROR line.

        Returns:
            Tuple of (succeeded, reason, relevant log lines)
        """
        began, finished, aborted_re = _run_markers(run_name)
        starts = [m.start() for m in began.finditer(log_text)]
        if not starts:
            return False, f"the run log has no 'Began computing' note (NOTE 15301) for run '{run_name}'", []
        start = starts[-1]
        following = _RUN_BEGAN_ANY.search(log_text, start + 1)
        section = log_text[start:following.start() if following else len(log_text)]

        errors = [m.group(0).strip() for m in _LOG_ERROR.finditer(section)]
        aborted = [m.group(0).strip() for m in aborted_re.finditer(section)]
        if aborted:
            return False, "HEC-HMS aborted the run (WARNING 15303)", errors + aborted
        if errors:
            return False, "the run log contains ERROR messages", errors
        if not finished.search(section):
            return False, f"the run log has no 'Finished computing' note (NOTE 15302) for run '{run_name}'", []
        return True, "finished computing (NOTE 15302)", []

    @staticmethod
    def _verify_run(script_success: bool, snapshot: Dict[str, Any], stdout: str = "") -> bool:
        """
        Confirm from the run's own outputs that HEC-HMS computed the run.

        ``snapshot`` comes from :meth:`_snapshot_run`, taken just before
        launch; this call also releases it (:meth:`_release_snapshot`).
        Checks, in order:

        1. the run declares a ``Log File`` and a ``DSS File`` (otherwise the
           run cannot be verified and False is returned);
        2. the script's own result;
        3. a run log exists. The prior log was moved aside before launch, so
           it was written by this run. It must have a section for this run
           that :meth:`_check_run_log` accepts;
        4. the results DSS file exists and changed since the snapshot (it is
           new, or its size, modification time or SHA-256 differs).

        Nothing is compared with the clock, so clock skew between this
        computer and a file server does not matter. A changed DSS file does
        not show which run wrote it; the run identity comes from the log.

        Returns:
            True only if every check passes. The reason for a failure and the
            relevant log lines are logged at ERROR level.
        """
        try:
            return HmsCmdr._verify_outputs(script_success, snapshot, stdout)
        finally:
            HmsCmdr._release_snapshot(snapshot)

    @staticmethod
    def _verify_outputs(script_success: bool, snapshot: Dict[str, Any], stdout: str) -> bool:
        run_name = snapshot["run_name"]

        def fail(reason: str, lines: Optional[List[str]] = None) -> bool:
            logger.error(f"Run '{run_name}' failed: {reason}.")
            for line in (lines or [])[:20]:
                logger.error(f"  {line}")
            return False

        if snapshot.get("problem"):
            return fail(snapshot["problem"])

        log_path, dss_before = snapshot["log_path"], snapshot["dss"]
        dss_path = dss_before["path"]
        try:
            log_text = HmsCmdr._read_log_text(log_path) if log_path.exists() else None
            dss_after = HmsCmdr._file_state(dss_path, _DSS_HASH_LIMIT_BYTES)
        except OSError as e:
            return fail(f"could not read the run outputs after the run: {e}")

        if not script_success:
            lines: List[str] = []
            if log_text is not None:
                _, _, lines = HmsCmdr._check_run_log(log_text, run_name)
            if not lines and stdout:
                lines = [
                    ln.strip() for ln in stdout.splitlines()
                    if ln.strip().startswith(("ERROR", "Error"))
                ]
            return fail("the HEC-HMS script did not complete", lines)

        if log_text is None:
            return fail(f"no run log was written ({log_path.name})")

        ok, reason, lines = HmsCmdr._check_run_log(log_text, run_name)
        if not ok:
            return fail(f"{reason}; see {log_path.name}", lines)

        if not dss_after["exists"]:
            return fail(f"the results DSS file {dss_path.name} was not written")
        dss_changed = not dss_before["exists"] or any(
            dss_after.get(key) != dss_before.get(key) for key in ("size", "mtime_ns", "sha256")
        )
        if not dss_changed:
            return fail(f"the results DSS file {dss_path.name} was not changed by this run")

        logger.debug(f"Run '{run_name}' verified: {reason}; log {log_path.name}")
        return True

    @staticmethod
    def _copy_project(
        source_folder: Path,
        dest_folder: Path,
        overwrite: bool = False
    ) -> Path:
        """
        Copy an HMS project to a new location.

        Args:
            source_folder: Source project folder
            dest_folder: Destination folder
            overwrite: Whether to overwrite existing destination

        Returns:
            Path to the copied project
        """
        if dest_folder.exists():
            if overwrite:
                shutil.rmtree(dest_folder)
            else:
                raise FileExistsError(f"Destination exists: {dest_folder}")

        logger.debug(f"Copying project from {source_folder} to {dest_folder}")
        shutil.copytree(source_folder, dest_folder)

        return dest_folder

    @staticmethod
    def _cleanup_worker_folders(base_folder: Path) -> None:
        """Remove worker folders after parallel execution."""
        if base_folder.exists():
            for item in base_folder.iterdir():
                if item.is_dir() and item.name.startswith("worker_"):
                    try:
                        shutil.rmtree(item)
                    except Exception as e:
                        logger.warning(f"Could not remove {item}: {e}")

compute_run(run_name, hms_object=None, dest_folder=None, overwrite_dest=False, timeout=DEFAULT_EXECUTION_TIMEOUT, save_project=True, max_memory=None, initial_memory=None, additional_java_opts=None) staticmethod

Execute a single HEC-HMS simulation run.

Parameters:

Name Type Description Default
run_name str

Name of the simulation run to execute

required
hms_object

Optional HmsPrj instance (uses global hms if None)

None
dest_folder Optional[Union[str, Path]]

Optional destination folder for execution (copies project there first)

None
overwrite_dest bool

Whether to overwrite existing destination

False
timeout int

Seconds for the whole call: waiting for another compute on the same dest_folder or output files, and running HEC-HMS (which gets only the time left after any wait)

DEFAULT_EXECUTION_TIMEOUT
save_project bool

Whether to save project after computation

True
max_memory str

Maximum JVM heap size (default: "4G") Examples: "4G", "8G", "16G" for large models

None
initial_memory str

Initial JVM heap size (default: "128M")

None
additional_java_opts Optional[List[str]]

Extra JVM options Examples: ["-XX:+UseG1GC", "-XX:MaxGCPauseMillis=200"]

None

Returns:

Type Description
bool

True only if HEC-HMS computed the run in this call. The log file

bool

and results DSS file are those the run's .run entry names

bool

(Log File:, DSS File:). Both files (and dest_folder,

bool

if given) are locked across threads and processes from before

bool

launch until verification ends, so another compute cannot write

bool

them meanwhile; computes on other files are not held up. Before

bool

launch, an existing log is moved to a backup name unique to this

bool

call, <log name>.hms-commander-prev-<32 hex> (deleted

bool

afterwards if the run wrote a new log, moved back if not), and

bool

the DSS file's size, modification time and hash (up to 512 MB)

bool

are recorded. Then:

bool
  • the generated script reported no error;
bool
  • a run log exists (written while this call held the lock) and has a section for this run (NOTE 15301 ... "<run_name>") with the "Finished computing" note for it (NOTE 15302), no ERROR line and no "Aborted run" warning (WARNING 15303);
bool
  • the results DSS file is new, or its size, modification time or content hash changed.
bool

Nothing is compared with the clock. If the run, its Log File:

bool

or its DSS File: entry cannot be found, the run cannot be

bool

verified and False is returned. False otherwise as well; the

bool

reason and the relevant log lines are logged at ERROR level.

Raises:

Type Description
RuntimeError

If the project is not initialized, or if no hms_exe_path was given and no installed HEC-HMS suits the project's Version: (equal, a newer patch of the same major.minor, or a newer major.minor), or if that Version: is not a comparable version. An older HEC-HMS is never chosen automatically. Also if this thread is already computing with the same output files (a nested call).

TimeoutError

If another compute holds the run's output files (or dest_folder) until timeout runs out, or no time is left to run HEC-HMS once they are free. timeout is one budget for waiting and running; HEC-HMS gets only what is left after any wait.

Note

Without hms_exe_path, the HEC-HMS version is chosen from the project's .hms file Version: line; see :meth:HmsJython.find_hms_executable.

Example

from hms_commander import HmsCmdr, init_hms_project init_hms_project(r"C:/Projects/MyProject", hms_exe_path=r"C:/HEC/HEC-HMS/4.9/hec-hms.cmd") success = HmsCmdr.compute_run("Run 1")

For large models:

success = HmsCmdr.compute_run("Run 1", max_memory="16G")

Source code in hms_commander/HmsCmdr.py
@staticmethod
@log_call
def compute_run(
    run_name: str,
    hms_object=None,
    dest_folder: Optional[Union[str, Path]] = None,
    overwrite_dest: bool = False,
    timeout: int = DEFAULT_EXECUTION_TIMEOUT,
    save_project: bool = True,
    max_memory: str = None,
    initial_memory: str = None,
    additional_java_opts: Optional[List[str]] = None
) -> bool:
    """
    Execute a single HEC-HMS simulation run.

    Args:
        run_name: Name of the simulation run to execute
        hms_object: Optional HmsPrj instance (uses global hms if None)
        dest_folder: Optional destination folder for execution
                    (copies project there first)
        overwrite_dest: Whether to overwrite existing destination
        timeout: Seconds for the whole call: waiting for another compute
            on the same ``dest_folder`` or output files, and running HEC-HMS
            (which gets only the time left after any wait)
        save_project: Whether to save project after computation
        max_memory: Maximum JVM heap size (default: "4G")
                   Examples: "4G", "8G", "16G" for large models
        initial_memory: Initial JVM heap size (default: "128M")
        additional_java_opts: Extra JVM options
                   Examples: ["-XX:+UseG1GC", "-XX:MaxGCPauseMillis=200"]

    Returns:
        True only if HEC-HMS computed the run in this call. The log file
        and results DSS file are those the run's ``.run`` entry names
        (``Log File:``, ``DSS File:``). Both files (and ``dest_folder``,
        if given) are locked across threads and processes from before
        launch until verification ends, so another compute cannot write
        them meanwhile; computes on other files are not held up. Before
        launch, an existing log is moved to a backup name unique to this
        call, ``<log name>.hms-commander-prev-<32 hex>`` (deleted
        afterwards if the run wrote a new log, moved back if not), and
        the DSS file's size, modification time and hash (up to 512 MB)
        are recorded. Then:

        - the generated script reported no error;
        - a run log exists (written while this call held the lock) and
          has a section for this run (``NOTE 15301 ... "<run_name>"``)
          with the "Finished computing" note for it (NOTE 15302), no
          ERROR line and no "Aborted run" warning (WARNING 15303);
        - the results DSS file is new, or its size, modification time or
          content hash changed.

        Nothing is compared with the clock. If the run, its ``Log File:``
        or its ``DSS File:`` entry cannot be found, the run cannot be
        verified and False is returned. False otherwise as well; the
        reason and the relevant log lines are logged at ERROR level.

    Raises:
        RuntimeError: If the project is not initialized, or if no
            ``hms_exe_path`` was given and no installed HEC-HMS suits the
            project's ``Version:`` (equal, a newer patch of the same
            major.minor, or a newer major.minor), or if that ``Version:``
            is not a comparable version. An older HEC-HMS is never chosen
            automatically. Also if this thread is already computing with
            the same output files (a nested call).
        TimeoutError: If another compute holds the run's output files
            (or ``dest_folder``) until ``timeout`` runs out, or no time is
            left to run HEC-HMS once they are free. ``timeout`` is one
            budget for waiting and running; HEC-HMS gets only what is
            left after any wait.

    Note:
        Without ``hms_exe_path``, the HEC-HMS version is chosen from the
        project's ``.hms`` file ``Version:`` line; see
        :meth:`HmsJython.find_hms_executable`.

    Example:
        >>> from hms_commander import HmsCmdr, init_hms_project
        >>> init_hms_project(r"C:/Projects/MyProject", hms_exe_path=r"C:/HEC/HEC-HMS/4.9/hec-hms.cmd")
        >>> success = HmsCmdr.compute_run("Run 1")
        >>> # For large models:
        >>> success = HmsCmdr.compute_run("Run 1", max_memory="16G")
    """
    from .HmsPrj import hms
    hms_obj = hms_object or hms

    if hms_obj is None or not hms_obj.initialized:
        raise RuntimeError("HMS project not initialized. Call init_hms_project() first.")

    HmsCmdr._ensure_hms_executable(hms_obj)

    # One budget for the whole call: waiting for locks and running HEC-HMS.
    deadline = time.monotonic() + timeout

    # A copied destination folder is locked while it is filled and
    # computed, so a concurrent call cannot replace it meanwhile.
    dest_lock = (
        OutputLock([Path(dest_folder)], deadline, purpose=f"copy for run '{run_name}'")
        if dest_folder else contextlib.nullcontext()
    )
    with dest_lock:
        # Determine working directory
        if dest_folder:
            dest_folder = Path(dest_folder)
            working_project = HmsCmdr._copy_project(
                hms_obj.project_folder,
                dest_folder,
                overwrite_dest
            )
        else:
            working_project = hms_obj.project_folder

        logger.info(f"Computing run '{run_name}' in {working_project}")

        # Generate script
        script = HmsJython.generate_compute_script(
            project_path=working_project,
            run_name=run_name,
            save_project=save_project
        )

        # Execute
        success, stdout, stderr = HmsCmdr._execute_and_verify(
            run_name, working_project, script,
            hms_exe_path=hms_obj.hms_exe_path,
            timeout=timeout,
            max_memory=max_memory,
            initial_memory=initial_memory,
            additional_java_opts=additional_java_opts,
            deadline=deadline,
        )

    if success:
        logger.info(f"Run '{run_name}' completed successfully")
    else:
        logger.error(
            f"Run '{run_name}' failed. "
            f"See: https://hms-commander.readthedocs.io/user-guide/execution/"
        )
        if stderr:
            logger.error(f"Error output: {stderr}")

    return success

compute_parallel(run_names=None, max_workers=2, hms_object=None, dest_folder=None, timeout_per_run=DEFAULT_EXECUTION_TIMEOUT, max_memory=None, initial_memory=None, additional_java_opts=None) staticmethod

Execute multiple HEC-HMS runs in parallel using worker folders.

Each run is executed in a separate copy of the project to avoid conflicts. This is the recommended method for batch processing.

Parameters:

Name Type Description Default
run_names Optional[List[str]]

List of run names to execute (all runs if None)

None
max_workers int

Maximum number of parallel workers

2
hms_object

Optional HmsPrj instance

None
dest_folder Optional[Union[str, Path]]

Base folder for worker copies

None
timeout_per_run int

Seconds for each run, from when it gets a worker folder: waiting for another compute on the same folder or output files, and running HEC-HMS

DEFAULT_EXECUTION_TIMEOUT
max_memory str

Maximum JVM heap size (default: "4G")

None
initial_memory str

Initial JVM heap size (default: "128M")

None
additional_java_opts Optional[List[str]]

Extra JVM options

None

Returns:

Type Description
Dict[str, bool]

Dictionary mapping run names to success status.

Dict[str, bool]

Each run is verified as in :meth:compute_run (run log section

Dict[str, bool]

for that run, changed results DSS, compared with a pre-launch

Dict[str, bool]

record). If no hms_exe_path is set, the HEC-HMS version is

Dict[str, bool]

chosen as in :meth:compute_run; RuntimeError is raised when no

Dict[str, bool]

installation suits the project's Version:.

Dict[str, bool]

A run whose worker folder or output files another compute holds

Dict[str, bool]

until timeout_per_run runs out is reported as False, with the

Dict[str, bool]

TimeoutError logged; the other runs continue.

Example

results = HmsCmdr.compute_parallel( ... ["Run 1", "Run 2", "Run 3"], ... max_workers=3 ... ) for run, success in results.items(): ... print(f"{run}: {'OK' if success else 'FAILED'}")

Source code in hms_commander/HmsCmdr.py
@staticmethod
@log_call
def compute_parallel(
    run_names: Optional[List[str]] = None,
    max_workers: int = 2,
    hms_object=None,
    dest_folder: Optional[Union[str, Path]] = None,
    timeout_per_run: int = DEFAULT_EXECUTION_TIMEOUT,
    max_memory: str = None,
    initial_memory: str = None,
    additional_java_opts: Optional[List[str]] = None
) -> Dict[str, bool]:
    """
    Execute multiple HEC-HMS runs in parallel using worker folders.

    Each run is executed in a separate copy of the project to avoid
    conflicts. This is the recommended method for batch processing.

    Args:
        run_names: List of run names to execute (all runs if None)
        max_workers: Maximum number of parallel workers
        hms_object: Optional HmsPrj instance
        dest_folder: Base folder for worker copies
        timeout_per_run: Seconds for each run, from when it gets a worker
            folder: waiting for another compute on the same folder or
            output files, and running HEC-HMS
        max_memory: Maximum JVM heap size (default: "4G")
        initial_memory: Initial JVM heap size (default: "128M")
        additional_java_opts: Extra JVM options

    Returns:
        Dictionary mapping run names to success status.
        Each run is verified as in :meth:`compute_run` (run log section
        for that run, changed results DSS, compared with a pre-launch
        record). If no ``hms_exe_path`` is set, the HEC-HMS version is
        chosen as in :meth:`compute_run`; RuntimeError is raised when no
        installation suits the project's ``Version:``.
        A run whose worker folder or output files another compute holds
        until ``timeout_per_run`` runs out is reported as False, with the
        ``TimeoutError`` logged; the other runs continue.

    Example:
        >>> results = HmsCmdr.compute_parallel(
        ...     ["Run 1", "Run 2", "Run 3"],
        ...     max_workers=3
        ... )
        >>> for run, success in results.items():
        ...     print(f"{run}: {'OK' if success else 'FAILED'}")
    """
    from .HmsPrj import hms
    hms_obj = hms_object or hms

    if hms_obj is None or not hms_obj.initialized:
        raise RuntimeError("HMS project not initialized")

    # Get run names if not specified
    if run_names is None:
        if hms_obj.run_df.empty:
            raise ValueError("No runs found in project")
        run_names = hms_obj.run_df['name'].tolist()

    if not run_names:
        logger.warning("No runs to execute")
        return {}

    HmsCmdr._ensure_hms_executable(hms_obj)

    # Set up destination folder
    if dest_folder:
        base_dest = Path(dest_folder)
    else:
        base_dest = hms_obj.project_folder.parent / f"{hms_obj.project_name}_workers"

    base_dest.mkdir(parents=True, exist_ok=True)

    logger.info(f"Starting parallel execution of {len(run_names)} runs with {max_workers} workers")
    results = {}

    # Each running task takes a free worker folder and returns it when
    # done, so no two runs ever use the same folder at once.
    free_workers: "queue.Queue[int]" = queue.Queue()
    for worker_id in range(max_workers):
        free_workers.put(worker_id)

    def execute_worker(run_name: str) -> Tuple[str, bool]:
        """Execute a single run in a free worker folder."""
        worker_id = free_workers.get()
        worker_folder = base_dest / f"worker_{worker_id}"
        # The run's budget (lock waits and execution) starts once it has
        # a worker folder.
        deadline = time.monotonic() + timeout_per_run

        try:
            # The worker folder is also locked across processes, in case
            # another call uses the same dest_folder.
            with OutputLock([worker_folder], deadline,
                            purpose=f"worker for run '{run_name}'"):
                # Copy project to worker folder
                working_project = HmsCmdr._copy_project(
                    hms_obj.project_folder,
                    worker_folder,
                    overwrite=True
                )

                # Generate and execute script
                script = HmsJython.generate_compute_script(
                    project_path=working_project,
                    run_name=run_name,
                    save_project=True
                )

                success, stdout, stderr = HmsCmdr._execute_and_verify(
                    run_name, working_project, script,
                    hms_exe_path=hms_obj.hms_exe_path,
                    timeout=timeout_per_run,
                    max_memory=max_memory,
                    initial_memory=initial_memory,
                    additional_java_opts=additional_java_opts,
                    deadline=deadline,
                )
            return run_name, success

        except Exception as e:
            logger.error(f"Worker {worker_id} failed for '{run_name}': {e}")
            return run_name, False
        finally:
            free_workers.put(worker_id)

    # Execute in parallel
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = {}
        for run_name in run_names:
            future = executor.submit(execute_worker, run_name)
            futures[future] = run_name

        for future in concurrent.futures.as_completed(futures):
            run_name, success = future.result()
            results[run_name] = success
            status = "completed" if success else "FAILED"
            logger.info(f"Run '{run_name}' {status}")

    # Summary
    successful = sum(1 for s in results.values() if s)
    failed = len(results) - successful
    logger.info(f"Parallel execution complete: {successful} succeeded, {failed} failed")

    return results

compute_batch(run_names, hms_object=None, save_after_each=False, timeout=7200, max_memory=None, initial_memory=None, additional_java_opts=None) staticmethod

Execute multiple runs sequentially in a single HMS session.

This is more efficient than compute_parallel when runs don't conflict and don't need separate output files. Runs that share a run log are computed one HMS session per run instead (see Returns).

Parameters:

Name Type Description Default
run_names List[str]

List of run names to execute

required
hms_object

Optional HmsPrj instance

None
save_after_each bool

Whether to save project after each run

False
timeout int

Seconds for the whole batch: every wait for another compute on the same output files and every HEC-HMS session

7200
max_memory str

Maximum JVM heap size (default: "4G")

None
initial_memory str

Initial JVM heap size (default: "128M")

None
additional_java_opts Optional[List[str]]

Extra JVM options

None

Returns:

Type Description
Dict[str, bool]

Dictionary mapping run names to success status.

Dict[str, bool]

Each run is verified as in :meth:compute_run (run log section

Dict[str, bool]

for that run, changed results DSS, compared with a pre-launch

Dict[str, bool]

record). If no hms_exe_path is set, the HEC-HMS version is

Dict[str, bool]

chosen as in :meth:compute_run; RuntimeError is raised when no

Dict[str, bool]

installation suits the project's Version:.

Dict[str, bool]

When runs share a Log File:, HEC-HMS would keep only the last

Dict[str, bool]

run's section in one session, so each run is computed in its own

Dict[str, bool]

HEC-HMS session, in the given order, and verified before the next

Dict[str, bool]

starts. timeout then covers all of these sessions together.

Dict[str, bool]

Runs that share a DSS File: cannot tell from the DSS file

Dict[str, bool]

which of them wrote it, so the log decides.

Raises:

Type Description
RuntimeError

If the project is not initialized, or no installation suits the project's Version:.

TimeoutError

If another compute holds the runs' output files until timeout runs out, or no time is left to run HEC-HMS once they are free. With per-run sessions, runs completed before that are not reported; a run reached after the budget is used up without waiting is reported as False.

Example

results = HmsCmdr.compute_batch(["Run 1", "Run 2", "Run 3"])

Source code in hms_commander/HmsCmdr.py
@staticmethod
@log_call
def compute_batch(
    run_names: List[str],
    hms_object=None,
    save_after_each: bool = False,
    timeout: int = 7200,
    max_memory: str = None,
    initial_memory: str = None,
    additional_java_opts: Optional[List[str]] = None
) -> Dict[str, bool]:
    """
    Execute multiple runs sequentially in a single HMS session.

    This is more efficient than compute_parallel when runs don't conflict
    and don't need separate output files. Runs that share a run log are
    computed one HMS session per run instead (see Returns).

    Args:
        run_names: List of run names to execute
        hms_object: Optional HmsPrj instance
        save_after_each: Whether to save project after each run
        timeout: Seconds for the whole batch: every wait for another
            compute on the same output files and every HEC-HMS session
        max_memory: Maximum JVM heap size (default: "4G")
        initial_memory: Initial JVM heap size (default: "128M")
        additional_java_opts: Extra JVM options

    Returns:
        Dictionary mapping run names to success status.
        Each run is verified as in :meth:`compute_run` (run log section
        for that run, changed results DSS, compared with a pre-launch
        record). If no ``hms_exe_path`` is set, the HEC-HMS version is
        chosen as in :meth:`compute_run`; RuntimeError is raised when no
        installation suits the project's ``Version:``.
        When runs share a ``Log File:``, HEC-HMS would keep only the last
        run's section in one session, so each run is computed in its own
        HEC-HMS session, in the given order, and verified before the next
        starts. ``timeout`` then covers all of these sessions together.
        Runs that share a ``DSS File:`` cannot tell from the DSS file
        which of them wrote it, so the log decides.

    Raises:
        RuntimeError: If the project is not initialized, or no
            installation suits the project's ``Version:``.
        TimeoutError: If another compute holds the runs' output files
            until ``timeout`` runs out, or no time is left to run HEC-HMS
            once they are free. With per-run sessions, runs completed
            before that are not reported; a run reached after the budget is
            used up without waiting is reported as False.

    Example:
        >>> results = HmsCmdr.compute_batch(["Run 1", "Run 2", "Run 3"])
    """
    from .HmsPrj import hms
    hms_obj = hms_object or hms

    if hms_obj is None or not hms_obj.initialized:
        raise RuntimeError("HMS project not initialized")

    if not run_names:
        logger.warning("No runs to execute")
        return {}

    HmsCmdr._ensure_hms_executable(hms_obj)

    logger.info(f"Starting batch execution of {len(run_names)} runs")

    project_folder = hms_obj.project_folder
    # One budget for the whole batch: lock waits and every HEC-HMS session.
    deadline = time.monotonic() + timeout
    shared = HmsCmdr._shared_log_runs(project_folder, run_names)
    results: Dict[str, bool] = {}

    if shared:
        # HEC-HMS rewrites a run log for every run it computes, so in one
        # session a shared log keeps only the last run's section. Compute
        # each run in its own session, in the given order, and verify it
        # before the next run can overwrite its log.
        for names in shared.values():
            logger.info(
                f"Runs {', '.join(repr(n) for n in names)} write the same run log; "
                "computing each run in its own HEC-HMS session so that each "
                "can be verified before the next."
            )
        for run_name in run_names:
            if remaining(deadline) <= 0:
                logger.error(
                    f"Run '{run_name}' not computed: the batch timeout of "
                    f"{timeout} s was used up by earlier runs."
                )
                results[run_name] = False
                continue
            script = HmsJython.generate_batch_compute_script(
                project_path=project_folder,
                run_names=[run_name],
                save_after_each=save_after_each
            )
            verified, stdout, _ = HmsCmdr._execute_and_verify(
                run_name, project_folder, script,
                hms_exe_path=hms_obj.hms_exe_path,
                timeout=timeout,
                max_memory=max_memory,
                initial_memory=initial_memory,
                additional_java_opts=additional_java_opts,
                deadline=deadline,
            )
            results[run_name] = verified
    else:
        # Generate batch script
        script = HmsJython.generate_batch_compute_script(
            project_path=project_folder,
            run_names=run_names,
            save_after_each=save_after_each
        )
        # Lock every run's outputs for the whole session, so no other
        # compute can write them between snapshot and verification.
        outputs = []
        for name in run_names:
            outputs.extend(HmsCmdr._run_output_files(project_folder, name)[:2])
        with OutputLock(outputs, deadline, purpose=f"batch in {Path(project_folder).name}"):
            snapshots = {
                name: HmsCmdr._snapshot_run(project_folder, name)
                for name in run_names
            }
            session_budget = remaining(deadline)
            if session_budget <= 0:
                for snapshot in snapshots.values():
                    HmsCmdr._release_snapshot(snapshot)
                raise TimeoutError(
                    "Batch not started: its time budget was used up waiting for "
                    "other computes on the same files."
                )

            # Execute
            try:
                success, stdout, stderr = HmsJython.execute_script(
                    script_content=script,
                    hms_exe_path=hms_obj.hms_exe_path,
                    working_dir=project_folder,
                    timeout=session_budget,
                    max_memory=max_memory,
                    initial_memory=initial_memory,
                    additional_java_opts=additional_java_opts
                )
            except BaseException:
                for snapshot in snapshots.values():
                    HmsCmdr._release_snapshot(snapshot)
                raise

            for run_name in run_names:
                # Default to overall success status
                status = success

                # Try to parse individual status from output
                if stdout:
                    if f"Completed: {run_name}" in stdout:
                        status = True
                    elif f"Error computing {run_name}" in stdout:
                        status = False

                # Confirm each run from its own run log and results DSS
                results[run_name] = HmsCmdr._verify_run(status, snapshots[run_name])

    # Summary
    successful = sum(1 for s in results.values() if s)
    failed = len(results) - successful
    logger.info(f"Batch execution complete: {successful} succeeded, {failed} failed")

    return results

compute_with_parameters(run_name, basin_name, parameter_modifications, hms_object=None, dest_folder=None, timeout=DEFAULT_EXECUTION_TIMEOUT, max_memory=None, initial_memory=None, additional_java_opts=None) staticmethod

Execute a run with modified parameters.

Useful for sensitivity analysis and calibration workflows.

Parameters:

Name Type Description Default
run_name str

Name of the simulation run

required
basin_name str

Name of the basin model to modify

required
parameter_modifications Dict[str, Dict[str, Any]]

Dictionary of element -> parameter changes

required
hms_object

Optional HmsPrj instance

None
dest_folder Optional[Union[str, Path]]

Destination for modified project

None
timeout int

Seconds for the whole call: waiting for another compute on the same destination or output files, and running HEC-HMS (which gets only the time left after any wait)

DEFAULT_EXECUTION_TIMEOUT
max_memory str

Maximum JVM heap size (default: "4G")

None
initial_memory str

Initial JVM heap size (default: "128M")

None
additional_java_opts Optional[List[str]]

Extra JVM options

None

Returns:

Type Description
bool

Tuple of (success, path to output folder).

Path

Each run is verified as in :meth:compute_run (run log section

Tuple[bool, Path]

for that run, changed results DSS, compared with a pre-launch

Tuple[bool, Path]

record). If no hms_exe_path is set, the HEC-HMS version is

Tuple[bool, Path]

chosen as in :meth:compute_run; RuntimeError is raised when no

Tuple[bool, Path]

installation suits the project's Version:.

Raises:

Type Description
RuntimeError

If the project is not initialized, or no installation suits the project's Version:.

TimeoutError

If another compute holds dest_folder or the run's output files until timeout runs out, or no time is left to run HEC-HMS once they are free.

Example

mods = { ... "Subbasin-1": {"CurveNumber": 80, "InitialAbstraction": 0.5}, ... "Subbasin-2": {"CurveNumber": 75} ... } success, output_path = HmsCmdr.compute_with_parameters( ... "Run 1", "Basin 1", mods ... )

Source code in hms_commander/HmsCmdr.py
@staticmethod
@log_call
def compute_with_parameters(
    run_name: str,
    basin_name: str,
    parameter_modifications: Dict[str, Dict[str, Any]],
    hms_object=None,
    dest_folder: Optional[Union[str, Path]] = None,
    timeout: int = DEFAULT_EXECUTION_TIMEOUT,
    max_memory: str = None,
    initial_memory: str = None,
    additional_java_opts: Optional[List[str]] = None
) -> Tuple[bool, Path]:
    """
    Execute a run with modified parameters.

    Useful for sensitivity analysis and calibration workflows.

    Args:
        run_name: Name of the simulation run
        basin_name: Name of the basin model to modify
        parameter_modifications: Dictionary of element -> parameter changes
        hms_object: Optional HmsPrj instance
        dest_folder: Destination for modified project
        timeout: Seconds for the whole call: waiting for another compute
            on the same destination or output files, and running HEC-HMS
            (which gets only the time left after any wait)
        max_memory: Maximum JVM heap size (default: "4G")
        initial_memory: Initial JVM heap size (default: "128M")
        additional_java_opts: Extra JVM options

    Returns:
        Tuple of (success, path to output folder).
        Each run is verified as in :meth:`compute_run` (run log section
        for that run, changed results DSS, compared with a pre-launch
        record). If no ``hms_exe_path`` is set, the HEC-HMS version is
        chosen as in :meth:`compute_run`; RuntimeError is raised when no
        installation suits the project's ``Version:``.

    Raises:
        RuntimeError: If the project is not initialized, or no
            installation suits the project's ``Version:``.
        TimeoutError: If another compute holds ``dest_folder`` or the run's
            output files until ``timeout`` runs out, or no time is left to
            run HEC-HMS once they are free.

    Example:
        >>> mods = {
        ...     "Subbasin-1": {"CurveNumber": 80, "InitialAbstraction": 0.5},
        ...     "Subbasin-2": {"CurveNumber": 75}
        ... }
        >>> success, output_path = HmsCmdr.compute_with_parameters(
        ...     "Run 1", "Basin 1", mods
        ... )
    """
    from .HmsPrj import hms
    hms_obj = hms_object or hms

    if hms_obj is None or not hms_obj.initialized:
        raise RuntimeError("HMS project not initialized")

    HmsCmdr._ensure_hms_executable(hms_obj)

    # Set up destination folder
    if dest_folder:
        dest_folder = Path(dest_folder)
    else:
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
        dest_folder = hms_obj.project_folder.parent / f"{hms_obj.project_name}_modified_{timestamp}"

    # The destination is locked while it is filled and computed, so a
    # concurrent call with the same dest_folder waits instead of
    # replacing it.
    # One budget for the whole call: waiting for locks and running HEC-HMS.
    deadline = time.monotonic() + timeout
    with OutputLock([dest_folder], deadline, purpose=f"copy for run '{run_name}'"):
        # Copy project
        working_project = HmsCmdr._copy_project(
            hms_obj.project_folder,
            dest_folder,
            overwrite=True
        )

        logger.info(f"Computing '{run_name}' with modified parameters in {working_project}")

        # Generate script with modifications
        script = HmsJython.generate_parameter_modification_script(
            project_path=working_project,
            basin_name=basin_name,
            modifications=parameter_modifications,
            run_name=run_name
        )

        # Execute
        success, stdout, stderr = HmsCmdr._execute_and_verify(
            run_name, working_project, script,
            hms_exe_path=hms_obj.hms_exe_path,
            timeout=timeout,
            max_memory=max_memory,
            initial_memory=initial_memory,
            additional_java_opts=additional_java_opts,
            deadline=deadline,
        )

    if success:
        logger.info(f"Modified run '{run_name}' completed successfully")
    else:
        logger.error(f"Modified run '{run_name}' failed")

    return success, working_project

verify_hms_installation(hms_exe_path=None) staticmethod

Verify HEC-HMS installation and return information.

Parameters:

Name Type Description Default
hms_exe_path Optional[Union[str, Path]]

Path to HEC-HMS executable (auto-detect if None)

None

Returns:

Type Description
Dict[str, Any]

Dictionary with installation information

Source code in hms_commander/HmsCmdr.py
@staticmethod
@log_call
def verify_hms_installation(
    hms_exe_path: Optional[Union[str, Path]] = None
) -> Dict[str, Any]:
    """
    Verify HEC-HMS installation and return information.

    Args:
        hms_exe_path: Path to HEC-HMS executable (auto-detect if None)

    Returns:
        Dictionary with installation information
    """
    result = {
        'found': False,
        'executable': None,
        'version': None,
        'java_home': os.environ.get('JAVA_HOME'),
        'hec_hms_home': os.environ.get('HEC_HMS_HOME')
    }

    if hms_exe_path:
        exe_path = Path(hms_exe_path)
    else:
        exe_path = HmsJython.find_hms_executable()

    if exe_path and exe_path.exists():
        result['found'] = True
        result['executable'] = str(exe_path)

        # Try to extract version from path
        path_parts = exe_path.parts
        for part in path_parts:
            if part.replace('.', '').isdigit() or (
                len(part) > 2 and part[0].isdigit() and '.' in part
            ):
                result['version'] = part
                break

    return result