rascommander/hec-ras-wine-precompute_6.6 repository overview

⁠HEC-RAS 6.6 Wine preprocessing

HEC-RAS 6.6 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.

⁠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 is a directory holding a Windows-style C: drive, installed programs, supporting DLLs, and Windows registry files. The image contains a prepared prefix at /runtime/wine-seed/prefix and its settings 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 there. The worker reads the installed template when making the copy, and directs normal job updates to the copy. UID 1000 cannot write the root-owned template; a container run as root could. 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.

Use a disposable 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_6.6: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_6.6: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. The published images passed the one-hour notebook on Windows paths containing spaces. See the Windows command and Linux options⁠ and test record⁠.

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

If Mermaid is unavailable in your viewer, the sequence is: Linux wrapper -> Windows Python under Wine -> ras-commander⁠ -> HEC-RAS -> files in the host mount. The worker returns its result to the wrapper, which writes the job receipt.

The wrapper launches Windows Python with xvfb-run -a -s "-screen 0 1024x768x24" wine, followed by the manifest's Python path and translated worker arguments. Inside RasPreprocess.preprocess_plan()⁠, a Windows Python subprocess launches the full executable path as "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 names and plan/geometry numbers determine the filenames. Other working files and calculation logs may also remain. Worker stdout/stderr are saved beside the receipt when the worker subprocess returns normally; early validation failures or forced timeouts can have less logging.

Exit code 0 means verified success, 1 a recorded job failure, and 2 a configuration or I/O error. The Windows Step 2b controller waits for the full batch before it stages files for the separate Linux calculation. Qualification here covers the retained two-stage sample with matching preprocessing and native solver versions. The tested simulation windows and limits are recorded below.

⁠Tested readiness

The published 6.6 image prepared both LF and CRLF versions of the full 266-hour ras2fim sample on Linux. Its prepared HDF was 2,681,108 bytes, retaining all 6,548 coordinate rows and populated hydraulic tables. Matching native computation produced 267 output times with finite water surfaces.

The one-hour Windows Docker Desktop notebook also passed with two CPUs per container, a host path containing spaces, and read-only dependency mounts. Native results contained two output times with 6,548 finite values each, and the prepared temporary HDF remained intact. Live progress, resume and batch continuation passed. The current release record⁠ records the full Linux and one-hour Windows scope.

⁠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-6.6 \
  --version 6.6

The manifest must declare "hec_ras_version": "6.6". 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-6.6 \
  --build-arg HEC_RAS_VERSION=6.6 \
  --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-6.6: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.