rascommander/hec-ras-wine-precompute_7.0.1 repository overview

⁠HEC-RAS 7.0.1 Wine preprocessing

HEC-RAS 7.0.1 is installed with Windows Python, dependencies, and saved TCU acceptance.

Qualification status: The matching image pairs passed the full 266-hour Linux sample and one-hour Windows Docker Desktop notebook at two CPUs per container, including progress, resume and batch checks. The current release record⁠ gives the results and limits. Published as v4 and latest; anonymous digest pulls are verified.

This Linux/amd64 container lets ras-commander⁠ call installed Windows HEC-RAS through Wine. HEC-RAS performs the preprocessing. The container provides the runtime and access to the host model folder.

A separate host HEC-RAS installation or external Wine profile mount is unnecessary.

⁠Models created on Windows or Linux

Pull the matching current image before running. Use a disposable model copy and mount its terrain and projection folders. With a model at /job, references to ..\source_terrain need /source_terrain; ..\projection needs /projection. The terrain HDF also needs its referenced TIFF files.

model_checks.py⁠ checks the selected inputs, existing 2D geometry, projection, terrain HDF and rasters before modifying model files. It normalizes the selected .prj, .p##, .g## and .u## to Windows CRLF, preserving other bytes. LF, CRLF and mixed inputs are accepted. The generated .x## remains LF.

Success requires both output HDFs to retain 2D areas and cell counts and contain valid cell-volume and face-area elevation tables. Receipts record these checks. File size and /Results presence are insufficient. See the full operating guide⁠.

⁠Wine, the HEC-RAS installation, and host data

Wine⁠ supplies Windows application interfaces on Linux. It lets Windows Python and the installed Windows HEC-RAS programs run inside this Linux container. ras-commander⁠ runs in Windows Python and calls HEC-RAS. HEC-RAS performs the preprocessing; the container supplies the operating environment.

⁠Where HEC-RAS is installed

A Wine prefix holds a Windows-style C: drive, programs, DLLs and registry. The image's prepared prefix is /runtime/wine-seed/prefix; settings are in /runtime/wine-seed/runtime.json.

At startup the wrapper copies the prepared prefix into the job's private scratch directory and sets WINEPREFIX to that copy. Wine can update its registry and temporary state in that private copy. The worker reads the installed template when making the copy; normal job updates use the copy. Windows Python is C:\Python311\python.exe; Xvfb supplies a virtual screen for the Windows application. No interactive desktop is needed for a prepared job.

⁠How inputs and outputs cross the host mount

For example, --mount type=bind,src=/shared/model,dst=/job makes the Docker host's /shared/model directory visible inside the container as /job. These are the same underlying files. There is no upload at startup or separate download at completion: opening /job/model.prj reads the host file, and writing /job/model.p01.tmp.hdf writes into the host directory.

Wine's Z: drive maps the container's Linux filesystem, so winepath -w can translate /job/model.prj to Z:\job\model.prj. That drive sees the container's filesystem and mounted folders. It does not expose unmounted host directories.

Docker resolves bind-mount source paths on the daemon's host. The command below uses ordinary container storage for temporary files. It does not request a memory-backed mount. Root can write the template path; the worker's copy-before-use behavior keeps normal Wine updates in the private prefix.

Use a disposable model copy and --user root for the qualified Windows Docker Desktop route. The job edits preprocessing settings and can replace generated files, including an existing final plan HDF when --replace-generated is set. The documented --rm run removes the container and its writable layer; the bind-mounted model folder remains.

⁠Run a preprocessing job

docker pull rascommander/hec-ras-wine-precompute_7.0.1:v4

docker run --rm --pull always --user root --cpus 2 \
  --mount "type=bind,src=/path/model,dst=/job" \
  --mount "type=bind,src=/path/source_terrain,dst=/source_terrain,readonly" \
  --mount "type=bind,src=/path/projection,dst=/projection,readonly" \
  rascommander/hec-ras-wine-precompute_7.0.1:v4 \
  prepare --project /job/model.prj --plan 01 --num-cores 2 --timeout 900 --replace-generated

Replace the source paths and project filename. In WSL use /mnt/c/... paths. For Windows Docker Desktop, use Windows source paths and one command line. See the Windows command and Linux options⁠ and test record⁠. Use the matching native Linux 7.0.1 image⁠ for the subsequent unsteady calculation. The Python operating guide⁠ and example notebook⁠ call both phases through linked ras-commander⁠ APIs on Windows or Linux.

Review and agree to the HEC-RAS Terms and Conditions for Use⁠. Vendor notices remain in the profile.

⁠CPU settings

The worker accepts --num-cores N, default 2, integer range 1-8. Pass Docker --cpus N with the same count. Docker limits shared CPU time; the worker uses RasPlan.set_num_cores()⁠ and RasPlan.set_2d_flow_options()⁠ with include_default=True to set the plan and each 2D mesh, then reads the explicit setting back⁠. The receipt records arguments.num_cores. One container prepares one plan; batch scheduling stays on the host.

The two-core setting passed the Linux full-plan and Windows one-hour sample qualification. The command above sets the same count in Docker and HEC-RAS.

⁠Installed code and GitHub source

The controller links identify source commit dc60b219091e85bcb4564eca45313475c39ce58a, used for the CPU-aligned source build described here. Its installed files were checked against that source.

The library is installed under C:\Python311\Lib\site-packages\ras_commander. Exact installed source: RasPrj.py⁠, RasPlan.py⁠, geom/GeomPreprocessor.py⁠, RasPreprocess.py⁠, RasTcu.py⁠, RasBco.py⁠, and ComputeResults.py⁠. All 239 package files in the retained 0.99.2 wheel match public commit 9e4217713e954236b0c16023e1815c6f2b7a5309 after normalizing line endings. The complete installed package source⁠ is inspectable on GitHub.

⁠Exact ras-commander call sequence

The tables link every ras-commander⁠ function shown below to the exact installed source. The calls below describe the qualified image.

sequenceDiagram
    participant Host as Host model folder mounted at /job
    box Linux controller in container
        participant L as prepare.py
    end
    box Wine environment in same container
        participant W as Windows Python worker
        participant C as ras-commander
        participant H as HEC-RAS
    end
    L->>L: Select runtime and copy private WINEPREFIX
    L->>W: xvfb-run + wine + Windows Python
    W->>W: Check model dependencies and normalize inputs to CRLF
    W->>C: RasPrj()
    W->>C: init_ras_project(..., accept_tcu=True)
    C->>C: RasTcu.status() and RasTcu.accept() if needed
    W->>C: RasPlan.get_plan_path(...)
    W->>C: RasPlan.set_num_cores(..., num_cores, refresh_dataframes=False)
    W->>C: RasPlan.set_2d_flow_options(..., cores=num_cores, include_default=True)
    W->>C: RasPlan.get_plan_value(..., "UNET D2 Cores")
    W->>C: GeomPreprocessor.clear_geompre_files(...)
    W->>C: RasPlan.update_run_flags(..., geometry_preprocessor=True)
    W->>C: RasPreprocess.preprocess_plan(...)
    C->>C: BcoMonitor.enable_detailed_logging(plan_file)
    C->>H: Ras.exe -c with quoted project and plan paths
    H->>Host: Read model and write preprocessing files through mount
    C->>C: BcoMonitor(...).monitor_until_signal(process)
    Note over C,H: BCO signal or owned unsteady process + fresh files
    C->>H: RasPreprocess._terminate_process_tree(process) if running
    C-->>W: PreprocessResult
    W->>W: Validate 2D mesh and hydraulic tables in both HDF files
    W-->>L: worker-result.json
    L->>Host: Confirm output files and write prepare.json through mount

The wrapper launches Windows Python through Wine and Xvfb. Inside RasPreprocess.preprocess_plan()⁠, a Windows subprocess invokes "Ras.exe" -c "<project.prj>" "<project.p01>" with shell=False.

BcoMonitor.monitor_until_signal()⁠ watches for Starting Unsteady Flow Computations. The alternate signal requires a RasUnsteady.exe descendant of this job's launcher and three nonempty output files changed from their prelaunch size/mtime baseline. The library uses psutil for process ownership and cleanup. The readiness limit is max_wait; the outer Windows worker subprocess has a separate timeout + 120 second limit.

The unsteady solver may start briefly before it is stopped. This workflow obtains preprocessing inputs for a separate calculation stage. A detected TCU dialog blocks the job. The wrapper requires the expected plan, geometry and output paths, an accepted bco or owned_process_artifacts readiness signal, timed_out=False, full_result_copied=False, and successful HDF-content validation before reporting success.

⁠What remains on the host

For plan 01 and geometry 01, HEC-RAS produces:

Project and plan/geometry numbers determine filenames. Worker stdout/stderr are saved beside the receipt when the subprocess returns normally.

Exit code 0 means verified success, 1 a recorded job failure, and 2 a configuration or I/O error. The matching native 7.0.1 container was tested as recorded below.

⁠Tested readiness

The published 7.0.1 image prepared both LF and CRLF versions of the full 266-hour ras2fim sample on Linux. Its prepared HDF was 4,676,101 bytes and retained all 6,548 coordinate rows and populated hydraulic tables. Matching native computation produced 267 output times with finite water surfaces throughout the mesh.

The published 6.5, 6.6 and 7.0.1 images passed the one-hour notebook on Windows Docker Desktop using root and a host folder containing spaces. Both stages used two CPUs, retained the prepared temporary HDF, and produced two output times with 6,548 finite water-surface values each. See the current release record⁠ for the full 266-hour Linux results and the one-hour Windows scope.

The installed HEC-RAS 7.0.1 application retains saved TCU state 701. The source and runtime inventory identify the exact installed files; test receipts identify the executing runtime.

Allow Docker storage for the image layers and a private Wine-prefix copy for each concurrent preparation.

⁠How to Re-Create this Container

The build starts with the exact controller source and a retained, prepared Wine profile outside Git. The full recreation guide⁠ records the installed prerequisites, profile preparation, TCU state, runtime export, verification and remaining reconstruction limits. A complete empty-prefix installation has not yet been demonstrated.

⁠Gather inspectable build inputs

Use controller commit dc60b219091e85bcb4564eca45313475c39ce58a of ras2fim-2d⁠:

The current runtime inventory⁠ lists all observed packages, installed source, runtime paths and image identities.

⁠Export the profile and build

Preserve the original profile and its Wine links. From the selected source checkout, export a new context containing only runtime.json and prefix/:

python containers/hecras-prepare/bundle_profile.py \
  --source /path/to/prepared-profile \
  --destination /path/to/external/wine-7.0.1 \
  --version 7.0.1

The manifest must declare "hec_ras_version": "7.0.1". The prepared prefix must contain the installed executable, Python environment, exact retained wheel and saved TCU state. Vendor installers, original profiles, model data and solver outputs remain outside the Git checkout and clean image context.

docker buildx build --load --platform linux/amd64 \
  --build-context hecras_runtime=/path/to/external/wine-7.0.1 \
  --build-arg HEC_RAS_VERSION=7.0.1 \
  --build-arg RAS_COMMANDER_COMMIT=9e4217713e954236b0c16023e1815c6f2b7a5309 \
  --build-arg RAS_COMMANDER_WHEEL_SHA256=dc0c2f9baa9db66afee01e34eb00d7a04f53e7b82c3340c786b2e9aef1795932 \
  --label org.opencontainers.image.revision=dc60b219091e85bcb4564eca45313475c39ce58a \
  --file containers/hecras-prepare/Dockerfile \
  --tag local/hecras-7.0.1:review .

Validate a fresh complete model with the local tag, --pull never, matching two-core options, and both stages. Retain receipts, HDF checks and logs. The recreation guide⁠ supplies the runtime audit command and full validation procedure.

The current release record⁠ records the published digests, anonymous pull checks and Linux/Windows test scope.

Contributed by CLB Engineering Corporation for ras2fim-2d.