Docker container API

RasDocker launches the Wine preparation and native Linux computation images through the Docker CLI. It does not use the Docker Python SDK. See Container Execution for working-copy layout, dependencies, and a complete two-stage example, and the container catalog for public images.

The host API and library embedded in an image can have different revisions. Record both when reproducing a run. The published image pairs cover HEC-RAS 6.5, 6.6, and 7.0.1; use the same version for both stages.

RasDocker

Call these static methods directly:

• preprocess_plan: run Windows HEC-RAS under Wine and retain a preparation receipt.
• compute_plan: run the matching native Linux unsteady solver from prepared inputs.
• run_plan: prepare and compute, stopping after failed preparation.
• run_batch: process independent working copies sequentially and retain a batch summary.

replace_generated=True permits replacement of generated model files; use a working copy. Each container bind-mounts the project read/write and optional dependencies read-only. The Docker engine must be able to access the source paths. Remote daemons do not automatically receive uploads through this API.

num_cores defaults to 2 and accepts integers 1–8. CPU quota and solver thread settings use that count. stream_callback receives live output and lifecycle events; resume=True reuses completed stages only after their retained evidence passes the resume checks. See the operating guide for callback and batch examples.

Static API for the two-container HEC-RAS workflow.

Use a disposable, complete model copy: both stages modify the project bind mount. Dependency mounts are read-only. A preprocessing success means the compiled inputs are ready; native computation subsequently produces the final plan HDF with unsteady results.

preprocess_plan staticmethod

Python

preprocess_plan(project_path: Union[str, Path], plan_number: Union[str, int], *, version: str = '6.5', image: Optional[str] = None, mounts: Optional[Mapping[str, Union[str, Path]]] = None, timeout: int = 900, num_cores: int = 2, replace_generated: bool = False, docker_executable: str = 'docker', pull: str = 'missing', run_id: Optional[str] = None, user: str = 'root', stream_callback: Optional[Any] = None, resume: bool = False, apparmor_profile: Optional[str] = None) -> ContainerResult

Create .tmp.hdf, .b## and .x## in the Wine image.

Parameters:

Name	Type	Description	Default
project_path	Union[str, Path]	Explicit host .prj file in a working model copy.	required
plan_number	Union[str, int]	Plan number, such as "01" or 1.	required
version	str	Matching HEC-RAS image version: "6.5", "6.6" or "7.0.1".	'6.5'
image	Optional[str]	Image override. Defaults to the published version's v4.	None
mounts	Optional[Mapping[str, Union[str, Path]]]	Container absolute destination to host source mapping, for example {"/source_terrain": terrain, "/projection": crs}. These mounts are read-only; the project folder is /job RW.	None
timeout	int	In-container timeout in seconds. Docker startup, pulling and shutdown receive an additional 120 seconds on the host. Pull a large image separately if the initial download is slow.	900
num_cores	int	Integer from 1 through 8 (default 2). Sets Docker's CPU quota and passes the same count to the in-container worker, which sets the selected HEC-RAS plan's processor count.	2
replace_generated	bool	Explicit permission to replace existing outputs. Defaults to False; use a fresh model copy when enabling it.	False
docker_executable	str	Docker CLI executable path, not a shell command.	'docker'
pull	str	Docker pull policy: "always", "missing" or "never". Use "always" to refresh an image published under the same tag.	'missing'
run_id	Optional[str]	Optional unique 1–64 character run ID. IDs cannot be reused, including after failed launches; omitted IDs are generated.	None
user	str	Container user; "root" supports Windows bind mounts.	'root'
apparmor_profile	Optional[str]	Optional AppArmor profile for the container (--security-opt apparmor=<profile>). Hosts whose default Docker profile denies Wine's sockets (wineserver: socket: Permission denied) need "unconfined" or a site profile.	None
stream_callback	Optional[Any]	Partial ExecutionCallback object. An optional on_container_event(event) receives project/stage identity, live stdout/stderr, validated completion and resume events. Ordinary callback exceptions are logged; interrupts propagate.	None
resume	bool	Reuse an unchanged successful stage recorded by this host API. Checks model, dependencies, options and output contents. A miss executes normally; it does not authorize replacement.	False

Returns:

Type	Description
ContainerResult	Receipt and process diagnostics; failed receipts
ContainerResult	are retained. Invalid inputs or reused run IDs raise before launch.

compute_plan staticmethod

Python

compute_plan(project_path: Union[str, Path], plan_number: Union[str, int], *, version: str = '6.5', image: Optional[str] = None, mounts: Optional[Mapping[str, Union[str, Path]]] = None, timeout: int = 14400, num_cores: int = 2, replace_generated: bool = False, docker_executable: str = 'docker', pull: str = 'missing', run_id: Optional[str] = None, user: str = 'root', prepare_receipt: Optional[Union[str, Path]] = None, stream_callback: Optional[Any] = None, resume: bool = False, apparmor_profile: Optional[str] = None) -> ContainerResult

Run preprocessed inputs with the native Linux unsteady solver image.

Parameters follow :meth:preprocess_plan. The default image is rascommander/hec-ras-linux-unsteady_{version}:v1. This stage passes num_cores to the container, whose worker calls :meth:RasCmdr.compute_plan_linux. Prepare matching-version inputs first. Successful native computation promotes .p##.tmp.hdf to .p##.hdf. prepare_receipt may explicitly select a prepare.json inside the project folder. Otherwise the worker selects the latest matching valid preparation receipt.

run_plan staticmethod

Python

run_plan(project_path: Union[str, Path], plan_number: Union[str, int], *, version: str = '6.5', preprocess_image: Optional[str] = None, compute_image: Optional[str] = None, mounts: Optional[Mapping[str, Union[str, Path]]] = None, preprocess_timeout: int = 900, compute_timeout: int = 14400, num_cores: int = 2, replace_generated: bool = False, docker_executable: str = 'docker', pull: str = 'missing', run_id: Optional[str] = None, user: str = 'root', stream_callback: Optional[Any] = None, resume: bool = False, apparmor_profile: Optional[str] = None) -> Tuple[ContainerResult, Optional[ContainerResult]]

Prepare then compute, stopping if preparation fails.

Returns (preparation, computation); computation is None after a failed preparation. An optional run ID is a prefix of at most 56 characters; -prepare and -compute identify separate receipts.

run_batch staticmethod

Python

run_batch(jobs: Iterable[Mapping[str, Any]], *, stage: str = 'run', **options) -> ContainerBatchResult

Run independent working copies sequentially and collect every outcome.

Each job maps project_path and plan_number plus optional overrides accepted by :meth:run_plan (stage='run'), :meth:preprocess_plan ('prepare'), or :meth:compute_plan ('compute'). Shared options, including resume and stream_callback, are keyword arguments. Job overrides win. A failed job does not prevent later jobs from running. KeyboardInterrupt stops the batch and cleans up the active container.

No pool runs inside a container. For concurrent jobs, an external scheduler can call the single-plan APIs on separate working folders. Summary rows identify success, reuse, durations, receipts and errors.

ContainerResult

Check success before using outputs. receipt_path is the expected path even when no receipt was produced; error, stdout, stderr, and returncode help diagnose host or container failures.

A Docker stage result, including its unmodified container receipt.

success requires both Docker exit zero and a successful receipt matching this invocation. receipt_path is the expected host path, even when a failure prevented receipt creation. error explains host-side failures; container diagnostics remain available in receipt, stdout and stderr. The result is bool-compatible.

ContainerBatchResult

Ordered per-job stage results and a stable, exportable summary_df.

Failed jobs remain in the summary. success is true only if every job succeeded; an empty batch is successful. Batch execution is on the host.

summary_df property

Python

summary_df

One row per submitted job, including skipped stages and failures.

Other container and scheduler APIs

RasPortableDocker, RasSlurm, and RasApptainer have separate execution contracts. Use the backend comparison to select an API before selecting an image.