2D Breakout Geometry Preparation¶
RasBreakout2D prepares the geometry and project associations for a contained
breakout of an existing pure-2D, unsteady HEC-RAS model. The API separates the
repeatable geometry work from unresolved hydraulic boundary-condition design.
The preparation workflow does not compute a plan or author a breakout boundary condition. It inventories the source boundaries, copies the complete unsteady file byte-for-byte, and returns parent-face flux evidence for later engineering review.
Qualify the proposed child domain¶
from pathlib import Path
from ras_commander import Breakout2DSpec, RasBreakout2D, RasPrj, init_ras_project
source_ras = RasPrj()
init_ras_project(
Path(r"D:\models\UPGU3"),
"6.6",
ras_object=source_ras,
load_results_summary=False,
)
spec = Breakout2DSpec(
source_plan="08",
source_2d_area="UPGU3_2DArea",
child_boundary=Path("huc12_121002010305.geojson"),
breakout_id="HUC12-121002010305",
)
preflight = RasBreakout2D.preflight(spec, ras_object=source_ras)
preflight.checks
preflight.feature_actions
preflight.existing_boundaries
preflight() fails closed unless the selected plan is unsteady and pure 2D,
the source geometry contains exactly one 2D flow area, the named area is
unique, the child polygon is valid and contained by the
parent, and no unsupported structure or reference-point edit is required.
SA/2D connections now receive complete-footprint keep, drop or block
decisions in feature_actions. A fully contained internal connection can remain
in the child, including a control whose From and To are the same retained area.
Fully external controls are individually reported before removal. Partial or
unknown physical support still blocks preparation. The single-area breakout
scope remains unchanged; this is not a multi-area seam authoring workflow.
The default blocks gates and undecoded support records. Set
Breakout2DSpec(allow_extended_connection_support=True, ...) to opt in to
verified gate opening GIS support, cell-size metadata and the additional empty
bridge template recognized by GeomLateral.classify_connections(). Preflight
and clone rechecks use the same choice; unrelated callers retain their defaults.
feature_actions.gate_group_count records verified gate groups and is zero for
other features. This opt-in does not establish native attachment or hydraulic
acceptance.
Preparation rechecks the approved decisions against the clone, requires fresh
native HDF refresh for connection edits, and compares the exact retained records
before and after geometry preparation. prepared.connection_attachments reports
native evidence separately. Rows without both named-end cell/face evidence carry
CONNECTION_ATTACHMENT_UNVERIFIED; successful text retention or preprocessing
alone cannot establish control qualification.
It classifies child-perimeter segments as inherited parent perimeter or artificial
cuts. Breaklines, reference lines, and refinement regions are classified as
keep, clip, or drop against a one-base-cell inward trim plus a small numeric
round-trip guard. Existing geometry BC lines and unsteady boundary records are
classified as preserve.
For a child that straddles adjacent parents, declare each additional parent's
geometry HDF in Breakout2DSpec(contributing_geometry_hdfs=("Adjacent.g01.hdf",)).
The default is (); relative paths resolve from the caller's current directory.
Preflight reads their complete native perimeters and checks containment against
their union with the owner. Each contributor must have exactly one 2D flow area,
a valid nonempty polygon and the owner's CRS. Contributor paths must end in
.gNN.hdf; .pNN.hdf paths are rejected before reading. The manifest records
each contributor path and SHA-256 captured while reading its perimeter.
This changes only child_within_parent to child_within_parent_union for that
preflight. All other checks, owner base spacing, feature actions and perimeter
segment classification retain their single-parent behavior. The clone still
contains one 2D flow area. The caller must independently qualify every contributor
and import its terrain, roughness, features and forcing before remeshing or
accepting a union child. Passing union containment alone qualifies no combined
hydraulic model.
Clone associations and prepare geometry¶
Initialize a separate, disposable project copy before calling the mutation methods:
working_ras = RasPrj()
init_ras_project(
Path(r"D:\working\UPGU3_breakout"),
"6.6",
ras_object=working_ras,
load_results_summary=False,
)
clone = RasBreakout2D.clone_plan_components(
preflight,
ras_object=working_ras,
plan_title="HUC12 breakout geometry prep",
plan_short_id="HUC12_PREP",
geometry_title="HUC12 breakout geometry",
)
prepared = RasBreakout2D.prepare_cloned_geometry(
preflight,
clone,
ras_object=working_ras,
refresh_hdf=True,
remesh=True,
compute_property_tables=False,
timeout=1200,
)
assert clone.boundaries_unchanged
assert prepared.boundaries_unchanged
For a cookie-cut bootstrap, pass the parent's selected physical cell centres as
computation_points (an N-by-2 XY array in the geometry's CRS and horizontal
units). Use refresh_hdf=True, refresh_method="rasexe", remesh=False and
anchor_grid_to_parent=False together. Preparation writes that set through
GeomMesh.write_computation_points instead of generating a regular grid. It
returns the text-writing result in prepared.computation_points_result and
then runs the normal native geometry preprocessor. No seeds are added, removed
or snapped; native fixed-width text serialization still applies. Every supplied
point must be unique, finite and strictly inside the child perimeter.
The native text round trip must preserve uniqueness and strict containment too;
field overflow is rejected. The writer preserves numbered .bak files and
atomically replaces the owned geometry text after all checks pass.
This is an explicit-point authoring primitive, not a claim of exact parent mesh reproduction. After compilation, the caller must check cell count, centre mapping, boundary faces and property tables. Native failure requires an explicit repair plan; the API does not silently generate a replacement point set. No hydraulic simulation is launched by preparation.
The clone operation creates new geometry, unsteady, and plan files; associates
the cloned plan with the new g## and u##; makes that plan current; and
registers the cloned geometry as a RASMapper geometry layer. It verifies both
plan associations by readback and proves the complete unsteady clone is
byte-identical with SHA-256. Before cloning, it also requires a separate
working project and verifies the working plan, geometry text, geometry HDF, and
unsteady source files against the qualified source with SHA-256.
Geometry preparation edits only the cloned geometry. It replaces the 2D
perimeter, trims mesh-owned features, performs the exact text-to-HDF refresh,
replaces refinement regions, regenerates computation cells, and audits domain
containment. The exact import transaction also protects and restores every
non-target geometry HDF because RASMapper can update older registered
geometries while opening a project. HEC-RAS may be opened for the exact
geometry import, but the hydraulic solver is never invoked. Install the
declared gui and mesh optional dependency groups when enabling the exact
refresh and remesh steps.
For headless refresh, set refresh_method="rasexe" and
require_complete_products=True to require qualified geometry completion.
The latter defaults to False for upstream compatibility and propagates to the
initial preprocessor call, numeric-repair retry, and mesh-repair preprocessing.
These completion checks do not establish hydraulic acceptance.
Review parent-face flux locations¶
flux = RasBreakout2D.review_parent_boundary_flux(
preflight,
minimum_peak_flow=100.0,
minimum_volume_fraction=0.0001,
)
flux.faces # every reviewed parent face and significance metrics
flux.zones # adjacent, same-direction candidate locations
flux.face_flow_outward # positive leaves the child; negative enters it
The review prefers stored parent Face Flow. When native Face Flow is unavailable, it derives normal flow from face-normal velocity and the face-area-versus-stage relationship. The result orients every series outward from the proposed child and groups adjacent significant faces that share the same dominant direction. A zone is review evidence only: it has no assigned HEC-RAS boundary type and does not modify a geometry or unsteady file.
Upper Guadalupe 3 qualification¶
The example notebook
959_ebfe_2d_breakout_geometry_preparation.ipynb
uses plan 08 and HUC12 121002010305 as a real-data qualification case. The
read-only preflight identified a 200-foot base cell, a contained 24.73-square-
mile child polygon, and 1,701 reviewed feature actions:
| Feature | Action | Count |
|---|---|---|
| Geometry BC lines | preserve | 4 |
| Unsteady boundary records | preserve | 4 |
| Breaklines | keep / clip / drop | 132 / 10 / 1,534 |
| Reference lines | keep / clip / drop | 1 / 1 / 13 |
| 2D mesh area | replace | 1 |
| Refinement regions | drop | 1 |
The existing u01 inventory contains Inflow_from_UPGU2 (Flow Hydrograph),
Outflow_to_UPGU4 (Normal Depth), BC_1 (Normal Depth), and BC_2 (Normal
Depth). Those records are parent-model inputs. Preserving them proves source
fidelity; it does not make them suitable for the breakout.
At the demonstration thresholds above, the already-computed parent result yielded 1,051 child-partition faces, 51 significant faces, and 22 combined same-direction candidate zones. No boundary condition was created or changed, and no hydraulic plan was rerun.
For rapid visual review, the notebook also shades the full parent with the
terrain-derived minimum elevation at each parent mesh cell, outlines a
review-scale p08 maximum-inundation boundary derived from wet parent cell
centers (maximum depth > 0.1 ft), and provides overall and detail maps of
candidate flux zones with outward-direction arrows. These are review figures
derived from existing HDF data, not new model results.
Next steps: author and validate boundary conditions¶
RasBreakout2D deliberately stops at geometry preparation; it does not infer
hydraulic forcing from parent face flow. The executed Austin Bayou SH 35
example notebook
continues from a reviewed compact child and demonstrates the separate APIs for
resetting its two geometry-backed boundary locations, writing a wide external
flow boundary, auditing native external-face ownership, and classifying
intersecting NextGen flowpaths. It explicitly selects a 1.5-mile reach from
the longer NextGen edge, derives a minimum domain envelope from connected wet
parent-result samples and a flat-ended reach corridor, and proves that the
implemented 2D domain contains both the complete selected reach and that
hydraulic evidence envelope. It then sums parent face flux at both child
cuts, derives an upstream flow envelope and preliminary downstream stage-flow
relationship, creates and computes one plan per 1,000-cfs ladder step, and
retains a comparable maximum-inundation map for every result. Each 48-hour
plan ramps to its target in four hours and holds a 44-hour plateau. The
notebook maps the selected parent faces with peak face-flux magnitude and
direction arrows, plots the imposed hydrographs, and reports final 12-hour
water-surface stability diagnostics with the computation summary.
That reviewed downstream workflow must:
- decide which artificial-cut candidate zones need hydraulic forcing;
- select the appropriate type for each location without inferring it solely from the direction or magnitude of parent Face Flow;
- source and time-align any parent flow or stage series;
- offset and trim geometry BC lines so adjacent records cannot bind the same face; and
- run and validate the breakout against the parent using a common terrain and aligned raster products where the meshes differ.
RasBreakout2D
¶
Static entry points for contained, pure-2D breakout preparation.
normalize_child_boundary
staticmethod
¶
normalize_child_boundary(child_boundary: BoundaryInput, parent_crs: Any, *, child_boundary_crs: Optional[Any] = None, breakout_id: str = 'breakout', allow_multipart: bool = False, allow_holes: bool = False) -> gpd.GeoDataFrame
Normalize one child polygon into the parent geometry CRS.
classify_boundary_segments
staticmethod
¶
classify_boundary_segments(parent_boundary: Union[BaseGeometry, GeoSeries, GeoDataFrame], child_boundary: Union[BaseGeometry, GeoSeries, GeoDataFrame], *, tolerance: float = 0.0, crs: Optional[Any] = None) -> gpd.GeoDataFrame
Partition the child perimeter into inherited and artificial cuts.
preflight
staticmethod
¶
Inventory and spatially qualify a breakout without modifying files.
clone_plan_components
staticmethod
¶
clone_plan_components(preflight: Breakout2DPreflight, *, ras_object: RasPrj, plan_title: Optional[str] = None, plan_short_id: Optional[str] = None, geometry_title: Optional[str] = None, set_current_plan: bool = True) -> Breakout2DCloneResult
Clone and associate the plan, geometry, and unsteady control file.
The caller must initialize ras_object on an isolated task-local
project. The complete unsteady file is copied without a title rewrite
and verified byte-for-byte before this method returns.
prepare_cloned_geometry
staticmethod
¶
prepare_cloned_geometry(preflight: Breakout2DPreflight, clone: Breakout2DCloneResult, *, ras_object: RasPrj, refresh_hdf: bool = True, refresh_method: str = 'rasmapper', remesh: bool = True, compute_property_tables: bool = False, timeout: int = 600, max_mesh_iterations: int = 8, disable_meteorology: bool = False, require_complete_products: bool = False, anchor_grid_to_parent: bool = False, computation_points: Optional[ndarray] = None, repair_computation_points: bool = False, parent_cell_ids: Optional[Sequence[int]] = None, native_worker_threads: Optional[int] = 1) -> Breakout2DPreparationResult
Trim mesh-owned features and remesh only the cloned geometry.
Geometry BC lines are not edited. The cloned unsteady file is preserved
unless disable_meteorology=True: after verifying the clone, inherited
meteorology and its source references are removed before native refresh.
Boundary hydrographs and infiltration remain unchanged. Mutation evidence
is returned in meteorology; boundaries_unchanged still reports
whole-file byte equality and is False when meteorology text changes. Planned refinement regions are applied to the cloned HDF
before perimeter and breakline text edits, while the inherited text
and HDF still match. refresh_hdf performs the exact text-to-HDF
import. With refresh_method="rasmapper" (default) it runs through the
owned RAS Mapper workflow. With refresh_method="rasexe" it runs
headless: computation points are first regenerated inside the new
perimeter (the parent's points would otherwise be imported), and
Ras.exe rebuilds the cloned geometry HDF through
:meth:GeomPreprocessor.run_geometry_preprocessor in geometry-only
mode. That pass also computes property tables, so the cloned HDF
must first carry a terrain association the child can resolve (set it
with :meth:RasMap.set_geometry_association).
RAS Mapper's text import replaces the HDF, so its HDF-only refinement
regions are reapplied after import. remesh then regenerates
computation cells through
:class:GeomMesh; no option launches a hydraulic simulation.
If native containment fails only for breaklines, a single recorded
retry may clip numerical endpoint deficits against the exact compiled
one-cell inward buffer. Each line must remain one positive LineString
and move at most 0.01 source horizontal units. Identities and mesh
controls remain fixed. The cloned geometry carries a planned/applied/
validated repair JSON sidecar; successful results also return the
records in breakline_containment_repairs. Larger deficits, dropped
or split lines, and structure violations remain blocking.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
preflight
|
Breakout2DPreflight
|
A passing :meth: |
required |
clone
|
Breakout2DCloneResult
|
The :meth: |
required |
ras_object
|
RasPrj
|
The initialized isolated working project. |
required |
refresh_hdf
|
bool
|
Rebuild the cloned geometry HDF from text. Required when connections are retained or removed. |
True
|
refresh_method
|
str
|
|
'rasmapper'
|
remesh
|
bool
|
Regenerate computation cells with :meth: |
True
|
compute_property_tables
|
bool
|
Compute 2D property tables afterwards. Requires a terrain association on the geometry. |
False
|
timeout
|
int
|
Seconds allowed for the text-to-HDF import. |
600
|
native_worker_threads
|
Optional[int]
|
Positive managed geometry worker-pool limit for headless refreshes, including a containment repair retry. Defaults to one; None retains inherited pool settings. This execution control does not change hydraulic solver cores. |
1
|
max_mesh_iterations
|
int
|
Mesh auto-fix iterations. |
8
|
computation_points
|
Optional[ndarray]
|
Optional N-by-2 XY coordinates in the source geometry CRS/units, for a cookie-cut bootstrap. Requires refresh_hdf=True, refresh_method="rasexe", remesh=False and anchor_grid_to_parent=False. Points are written unchanged through GeomMesh.write_computation_points unless repair_computation_points is enabled; native compilation and QA still follow. Writing supplied points does not establish parent face identity. |
None
|
repair_computation_points
|
bool
|
Opt in to the bounded supplied-seed MaxFaces/perimeter recipe before headless compilation. Requires computation_points. The returned computation_points_result's seed_repair records its plan and readback; default False leaves supplied points and perimeter unchanged. Native completion and hydraulic review remain required after repair. |
False
|
parent_cell_ids
|
Optional[Sequence[int]]
|
Explicit physical cell IDs from the source geometry
HDF. Retain their exact cell/face topology through
:meth: |
None
|
disable_meteorology
|
bool
|
Disable and remove inherited meteorological sources for an owned boundary-only child before preprocessing. Defaults to False for existing precipitation-driven workflows. |
False
|
require_complete_products
|
bool
|
Require the qualified completion contract for every native refresh, including numeric-repair retries and mesh repairs. Defaults to False for upstream compatibility. |
False
|
anchor_grid_to_parent
|
bool
|
Lay the child's regular computation-point
grid on the parent area's lattice
(:meth: |
False
|
Returns:
| Type | Description |
|---|---|
Breakout2DPreparationResult
|
Evidence for each preparation step. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If preflight did not pass, the clone's unsteady inputs
changed, |
RuntimeError
|
If the HDF refresh, remeshing or property tables fail. |
select_parent_boundary_faces
staticmethod
¶
select_parent_boundary_faces(geometry_hdf: Union[str, Path], mesh_name: str, child_boundary: Union[BaseGeometry, GeoSeries, GeoDataFrame]) -> gpd.GeoDataFrame
Select parent faces separating retained and discarded active cell centers.
Partition numeric topology first, constructing geometries only for the selected faces. Ghost cells are excluded when active cell counts exist.
review_parent_boundary_flux
staticmethod
¶
review_parent_boundary_flux(preflight: Breakout2DPreflight, *, minimum_peak_flow: float = 100.0, minimum_volume_fraction: float = 0.001, gap_multiplier: float = 3.0, prefer_native: bool = True) -> Breakout2DFluxReview
Summarize parent flux locations without assigning child BC types.