|
|
# BASEchange
|
|
|
|
|
|
> **Provisional module notice**
|
|
|
> BASEchange is still undergoing development and does not yet have a stable API.
|
|
|
>
|
|
|
> If your work requires a stable module API, please wait for a release version.
|
|
|
The BASEchange module provides support for 1D channel geometries, as well as reading and writing the BASEchain file format (`.BMG`).
|
|
|
|
|
|
The BASEchange module adds support for 1D geometries, as well as reading and writing BASEchain geometry files (.BMG).
|
|
|
Additionally, it exposes a command line interface (CLI) that allows generation and export of 1D channel geometries as 1D (`.BMG`) or 2D (`.2DM`) meshes respectively.
|
|
|
|
|
|
It also exposes a command line interface (CLI) to allow the generation and export of channel geometries as either 1D or 2D meshes in `.bmg` or `.2dm` format respectively.
|
|
|
This document only deals in the command line interface, the reasoning behind it, and the available switches and arguments. The module-level API is not covered here.
|
|
|
|
|
|
## Command line interface
|
|
|
|
|
|
The BASEchange CLI allows the generation of straight, trapezoidal channel geometries via the command line.
|
|
|
|
|
|
### Basic channel
|
|
|
|
|
|
| Switch | Full name | Default | Description |
|
|
|
|--------------------|-----------------------------|---------|----------------------------------------------------------------------------------------|
|
|
|
| `-LC <length>` | Channel length | 500.0 | Overall length of the channel |
|
|
|
| `-WC <width>` | Bed width | 50.0 | Bed width of the channel |
|
|
|
| `-S <slope>` | Channel slope | 0.0015 | Channel slope |
|
|
|
| `-B <slope>` | Bank slope | 1.0 | Slope of the channel banks |
|
|
|
| `-H <height>` | Channel height | 5.0 | Height of the channel flood plain relative to the channel bed |
|
|
|
| `-KS <strickler>` | Bed Strickler value | 35.0 | Friction of the channel bed |
|
|
|
| `-KSB <strickler>` | Banks Strickler value | 20.0 | Friction of the channel banks |
|
|
|
| `-X <offset>` | Offset along X axis | 0.0 | Moves the channel along its flow axis |
|
|
|
| `-Z <offset>` | Offset along Z axis | 0.0 | Raises the channel off the reference plane |
|
|
|
| `-N <num>` | Number of cross section | 100 | Number of cros sections to generate |
|
|
|
| `-CS <prefix>` | Cross section name prefix | 'CS' | This prefix will be appended with the cros section number to generate the unique names |
|
|
|
| `--R` | Reverse cross section order | (unset) | If set, cross section output order is reversed |
|
|
|
| `-MPS` | Midpoint shift | 0.5 | Relative position of the bank midpoint vertices |
|
|
|
| `--2D` | 2DM creation flag | (unset) | If set, also generate a 2DM mesh via Triangle |
|
|
|
| `--BED` | Add soil definitions | (unset) | If set, define a bottom range with soil index 1 |
|
|
|
| `-BS <node_index>` | Bed start index | 3 | Index of the node where the channel bed starts |
|
|
|
|
|
|
### Channels with widening
|
|
|
|
|
|
These channels support all of the basic channel tags.
|
|
|
|
|
|
In addition, the following tags are used to control the shape and position of the widened section:
|
|
|
|
|
|
| Switch | Full name | Default | Description |
|
|
|
|--------------------|--------------------------|---------|----------------------------------------------------------------------------------|
|
|
|
| `-LW <length>` | Widening length | 100.0 | The length of the straight, widened section |
|
|
|
| `-LT <length>` | Transition length | 20.0 | The length of the transitioning section between the regular and widened sections |
|
|
|
| `-WW <width>` | Widening width | 100.0 | Bed width of the widened section |
|
|
|
| `-KSW <strickler>` | Widening Strickler value | 30.0 | Strickler value for the channel bed in the widened section | |
|
|
The preferred way to access the BASEchange CLI is via its module-level script:
|
|
|
|
|
|
```
|
|
|
python -m basemesh.basechange [optional arguments here]
|
|
|
```
|
|
|
|
|
|
Alternatively, it can also be accessed directly through BASEmesh by passing the `--1D` flag:
|
|
|
|
|
|
```
|
|
|
python -m basemesh --1D [optional arguments here]
|
|
|
```
|
|
|
|
|
|
### Basic channel geometry
|
|
|
|
|
|
![basechange-illustration_straight-01](uploads/b11bea8f3777b58706237cd7544436fc/basechange-illustration_straight-01.png)
|
|
|
|
|
|
| Switch | Description | Default | Unit |
|
|
|
|-------------------|-----------------------------------------------|---------|------|
|
|
|
| `-DX <dx>` | Distance between cross sections | 40.0 | m |
|
|
|
| `-N <num_cs>` | Number of cross sections | 10 | - |
|
|
|
| `-S <slope>` | Channel slope (rise over run) | 0.0015 | - |
|
|
|
| `-WC <width>` | Channel bed width | 50.0 | m |
|
|
|
| `-B <slope>` | Bank slope (rise over run) | 1.0 | m |
|
|
|
| `-H <height>` | Floodplain height relative to the channel bed | 5.0 | m |
|
|
|
| `-MPS <mp_shift>` | Position of bank midpoint vertex (0.0 to 1.0) | 0.5 | - |
|
|
|
| `-X <offset_x>` | Offset along X axis (in flow direction) | 0.0 | m |
|
|
|
| `-Z <offset_z>` | Offset along Z axis (elevation) | 0.0 | m |
|
|
|
|
|
|
### Frictions
|
|
|
|
|
|
| Switch | Description | Default | Unit |
|
|
|
|-------------------|-------------------------------|---------|-----------|
|
|
|
| `-KS <ks_bed>` | Channel bed Strickler value | 35.0 | m^(1/3)/s |
|
|
|
| `-KSB <ks_banks>` | Channel banks Strickler value | 20.0 | m^(1/3)/s |
|
|
|
|
|
|
### Output options
|
|
|
|
|
|
| Switch | Description | Default |
|
|
|
|--------------------|-----------------------------------------------|---------|
|
|
|
| `-CS <prefix>` | Cross section name prefix (`<prefix>1`, etc.) | 'CS' |
|
|
|
| `--R` | If True, reverse cross section order | False |
|
|
|
| `--2D` | Export a 2D mesh instead of a 1D channel | False |
|
|
|
| `--BED` | Include a SOILDEF block in the output | False |
|
|
|
| `-BS <node_index>` | Starting index for channel bed definition | 3 |
|
|
|
|
|
|
### Widening options
|
|
|
|
|
|
Setting the `--widening` flag will include a widened section at the end of the straight channel. Note that this will dramatically increase the length of the channel when only using default arguments due to the way the widening is appended to the existing cross sections.
|
|
|
|
|
|
![basechange-illustration_widening-01](uploads/08c9697d8805e4dca10e4e859428f290/basechange-illustration_widening-01.png)
|
|
|
|
|
|
> **Important:** Note that while `N` and `NW` are specified including their start and end cross section, `NT` only controls the number of inserted, interpolated cross sections between the two uniform channels.
|
|
|
>
|
|
|
> This means that it is possible to set `NT` to 0, in which case `DXT` is still used to define the distance between the last cross section of the initial channel and the first cross section of the widened section.
|
|
|
|
|
|
| Switch | Description | Default | Unit |
|
|
|
|---------------------|-------------------------------------------------------|---------|-----------|
|
|
|
| `--widening` | Use widening (enables other flags in this section) | False | - |
|
|
|
| `-WW <w_bed_width>` | Bed width for the widening | 100.0 | m |
|
|
|
| `-KSW <w_ks_bed>` | Widening channel bed Strickler value | 30.0 | m^(1/3)/s |
|
|
|
| `-DXW <w_dx>` | Distance between cross sections in the widening | 30.0 | m |
|
|
|
| `-NW <w_num_cs>` | Number of cross sections in the widening | 5 | - |
|
|
|
| `-DXT <t_dx>` | Distance between cross sections in the transition | 20.0 | m |
|
|
|
| `-NT <t_num_cs>` | Number of cross sections inserted into the transition | 3 | - | |