Frequently asked questions

No. Nays2DH contains no sub-model for pollutant, solute or tracer transport, so the advection and diffusion of a substance such as NaCl cannot be computed with this solver. Nays2DH handles water flow and riverbed change (sediment transport) only. If a water-quality or tracer simulation is required, a different solver must be used; the list of iRIC solvers and their features can be checked on the iRIC website.

The vegetation density entered as a cell attribute corresponds to the parameter as in the vegetation-resistance formulation of the solver, and it must be given in metres. A value of 0 means no vegetation in that cell; any value of 0 or greater is accepted. The definition of as and the way it enters the drag term are described in the Nays2DH solver manual, section II.4 "Method of calculating resistance by vegetation", so check that section to convert your field data (stem diameter, spacing, etc.) into the required value. The theoretical background of vegetation resistance is covered by iRIC Academy.

The grid generators built into iRIC do not offer a convenient way to build a structured grid for a confluence, even though the Nays2DH manual describes tributary inflow layouts. The practical workaround is to create the structured grid in other software and import it into iRIC; the GUI accepts several grid file formats, including a simple CSV format documented in the iRIC GUI user manual ("Grid > Import" section on CSV grids). Note also that a structured-grid model such as Nays2DH has inherent limitations at confluences because the grid cannot follow both channels flexibly, so results near the junction should be interpreted with care. If the confluence geometry is important, consider an iRIC solver that uses an unstructured grid instead. A Japanese document with many diagrams about grid construction (cell aspect ratio and similar guidance) is available under "iRIC notes" in the download section of the iRIC site.

No. Nays2DH works only with structured (curvilinear, I-J) grids. If you need an unstructured mesh, for example for a river confluence or a complex plan shape, iRIC provides other 2D solvers that support it, such as SToRM, River2D and Mflow_02. A comparison spreadsheet of iRIC solvers and their features is linked from the iRIC forum and website, so use it to pick a solver that fits both the grid type and the physical processes you need (note that not all unstructured-grid solvers compute riverbed change).

The bank erosion calculation itself can be performed with Nays2DH: enable bed deformation and the bank erosion option in the calculation conditions, and the example cases distributed with the solver show the typical setup. The 3D animation seen in the demonstration videos, however, is not produced inside iRIC. The results are exported from iRIC and rendered with separate visualisation software such as ParaView, so you will need to export the results (for example in VTK format from the post-processing window) and build the animation there.

In one reported case this happened with a simple straight channel when the grid had been generated with the "Create grid by dividing rectangular region" algorithm, and it disappeared when the same channel was gridded with "Create grid shape solving Poisson equation". So the grid creation algorithm (and the way the topography is mapped onto it) is one possible cause; try regenerating the grid with the other algorithm and remapping the elevation. Another view expressed is that a short initial transient with reversed arrows is not necessarily wrong, because the flow field needs some time to adjust from the initial condition; judge the results after the flow has settled rather than in the first few seconds. If the reversal persists, check the bed slope of the mapped elevation and the upstream/downstream orientation of the grid.

The .riv format and the way it is created and edited are described in the iRIC GUI user manual, in the "River Survey Data" section of the geographic data chapter. In short, you prepare the cross-section data (centre line coordinates and, for each section, distance and elevation pairs) in the text layout given there, then import it via Import > Geographic Data > River Survey Data (or "Add" from the Object Browser). Once imported, the sections can be edited in the pre-processing window and used to create the grid with the "Create grid from river survey data" algorithm. Video tutorials exist, but the manual page is the authoritative reference for the file layout.

This message means the flow computation has diverged. The following remedies have resolved it in practice:

• Reduce the time step (dt). Cases that failed at 0.1 s or 0.001 s ran after going down to 0.0001 s. Time step and grid size go together, so change them as a pair.
• Coarsen the grid. For a sinuous-channel case, reducing the number of cells (for example to 10 across the channel and 20 per wavelength) with dt = 0.005 s allowed the run to complete.
• Disable bed deformation first to confirm that the flow alone is stable, then re-enable it.
• Check the grid geometry. Cells that cross or overlap, especially near the upstream end, can cause immediate failure; inspect the grid there.
• Check the boundary time series. A run that stops when a negative water level is given in the downstream time series but runs when the level is 0 is typically a stability issue; adjusting dx and dt was the suggested fix.

The relaxation coefficient for the water-surface calculation can also be tuned, as discussed in related forum threads. Expect some trial and error: there is no single correct dt, and the appropriate value depends on the cell size and flow velocity (Courant condition).

Choose the bed condition according to the problem: if only the flow matters (for example a channel with concrete bed and banks), run with the bed deformation disabled (fixed bed). If erosion and deposition are the subject, enable bed deformation (movable bed). Likewise, use a constant discharge for a steady-state case and a time series of discharge for an unsteady case such as a flood hydrograph; both are set in the boundary condition / time series section of the calculation conditions. For sediment properties, selecting the Advanced solver type (instead of Standard) exposes the non-uniform bed material settings where grain-size distribution curves can be entered, and a non-erodible layer can be given through the "Elevation of fixed bed" geographic data. The solvers distributed with iRIC are compiled executables, so they cannot be stepped through or debugged from the GUI; the console output is the only runtime information available.

There is no single correct choice, but a commonly used starting point is:

• Thickness of bedload layer: the maximum grain size (dmax) or d90 of the bed material.
• Thickness of deposited layer: about 2 × dmax.
• Thickness of movable bed layer under the initial bed (m): the actual thickness of erodible material, e.g. 0.01 if the sand layer in the experiment is 1 cm thick.

If the underlying fixed bed may become exposed, also set the Elevation of fixed bed (m) geographic data in the Object Browser and, in the calculation conditions, set "How to set elevation of fixed bed" to use that elevation data. These thicknesses control the layer bookkeeping of the grain-size mixing model; the theoretical background of the multi-layer model is covered by iRIC Academy.

Two things to do before running the calculation:

1. Re-map the polygon onto the grid: Grid > Attribute Mapping > Execute, tick Check All, then OK.
2. Confirm the mapping in the Object Browser: Grid > Cell attributes > Obstacle and tick the check box to display it.

Be aware of the mapping rule, which depends on the iRIC version. In iRIC 2.3 a polygon is mapped to a cell only if it contains all four corner nodes of that cell, so thin or small polygons (narrower than one cell) are never mapped. From iRIC 3.0 a cell is flagged as obstacle if the polygon contains the cell centre, which works much better for narrow structures. If the obstacle is still missing in iRIC 2.3, enlarge the polygon or refine the grid so that whole cells fall inside it, or upgrade to a newer iRIC.

The easiest way to learn the exact layout is to export a grid from iRIC itself: open any project, choose Grid > Export and save as CSV (see the grid export section of the iRIC GUI user manual). The exported file shows the required header and the order of the I, J, X, Y and elevation/attribute columns. Then reformat the external grid data to match that layout exactly and bring it in with Grid > Import (grid import section of the same manual). After importing, map the geographic data or check that the elevation attribute was read correctly before setting calculation conditions.

Nays2DH computes a uniform-flow depth at the boundaries from the bed slope before starting, and this iteration fails when the slope it is given is zero or reversed (bed rising in the downstream direction). This can easily happen when the slope is calculated from the grid and the local bed near the boundary is irregular, for example in a confluence experiment. The fix is to open the boundary condition settings in the calculation conditions and, for the slope used in the uniform flow calculation, choose to give a constant value instead of computing it from the geometry, then enter a positive slope representative of the channel.

When the specified stage is clearly higher than the lowest bed elevation but the solver still complains, the most likely cause is that the grid's downstream end is not where you think it is: the boundary condition is applied to the J-line that iRIC treats as the downstream end, which may be at a higher part of the channel or even at the upstream side if the grid was built in the reverse direction. For grids created from river survey data, the upstream and downstream ends are determined by the direction of the centre line, as illustrated in the figure of the "polygonal line and width" page of the iRIC GUI user manual. Check which end of the grid is downstream (the I index increases from upstream to downstream), and if necessary rebuild the grid with the centre line drawn in the correct direction.

Nays2DH does not have a user-defined threshold height above which a bar becomes impassable. What you see on bars at low flow is the minimum water depth that the solver keeps in every cell to stabilise the computation; cells at this minimum depth are effectively dry and no meaningful velocity is calculated there. So a depth contour alone can be misleading. Display the velocity contour or vectors instead: if the velocity on the bar is zero, the bar is not actually being overtopped.

The released version of Nays2DH cannot be set up with an initial condition of ponded water behind a gate that is suddenly removed; its initial condition is derived from the boundary discharges and the uniform-flow calculation. A similar case can be run with Nays2DFlood using its "bomber cells" feature, which removes selected cells (for example the gate) at a specified time and lets the stored water propagate downstream. Note that Nays2DFlood still requires at least one inflow point to be defined, otherwise it stops with an "inflow point is zero" message, so an inflow boundary must be set even if the discharge is small or zero.

No. iRIC does not support nested or refined (multi-level) grids, and there is no grid creation algorithm that produces such a grid from a polygon. Nays2DH uses a single structured grid, so the only way to increase resolution in an area of interest is to increase the number of divisions in the whole grid or to use a non-uniform division (denser I or J spacing) in the grid creation dialog, accepting that the refinement extends across the full row or column.

"Free Outflow" is one of the choices under Boundary Condition > Water surface at downstream. With this option, no fixed downstream water level is given. Instead, the solver takes the water depth computed in the cells just inside the downstream boundary and adds the bed elevation at the boundary edge to obtain the downstream water surface elevation. It is therefore a non-reflecting, computed outflow condition rather than a user-specified stage. The Nays2DH solver manual (around page 36 in the English edition) describes the downstream boundary options. The theoretical background of boundary conditions is covered in iRIC Academy.

Nays2DH does not have a separate setting for flow direction. The suggested approach is to drive the reversal through the downstream boundary: give the downstream water surface elevation as a time series (Boundary Condition > Water surface at downstream > time series) and let it rise and fall with the tide. When the downstream stage becomes higher than the water level inside the domain, the flow reverses and moves upstream; when it drops again, the flow returns to the normal downstream direction. Prepare the time series so that the tidal cycle is fully covered by the simulation period.

This message appears when the solver cannot compute the uniform-flow water depth used at the inflow boundary. A common cause is that the first value in the discharge time series is zero. Check both the main channel and the tributary discharge tables under Boundary Condition and make sure the discharge at the initial time is a non-zero value. Bed slope at the inflow section can also affect the uniform flow calculation, so confirm that the upstream end of each channel has a reasonable (non-negative, non-zero) slope. Fixing the initial discharge resolved the convergence message in the reported case; note that a subsequent "Calculation is failure" can still occur for other reasons such as the time step being too large for the grid size.

Nays2DH itself does not provide a time-independent maximum depth output. The recommended way is to export the calculation results for all time steps to text (CSV) files (File > Export > Calculation result, choosing CSV) and then compute the per-node maximum with an external tool such as a spreadsheet or a script. If a maximum-depth map is essential, note that Nays2DFlood can visualize the maximum water depth directly, so it may be worth considering that solver for inundation-type studies.

In practice, TIFF raster data is best converted before importing. Use a GIS package such as QGIS or ArcGIS to export the raster as an ASCII point file with X, Y and Z columns (for example a .tpo or .xyz text file). Then import that file in iRIC via Geographic Data > Elevation > Import, and map it to the grid with Grid > Attribute mapping. If the grid creation "did not work well" with the original raster, the conversion to XYZ points usually resolves the problem.

Nays2DH is a depth-averaged model, so dynamic pressure is not a separately solved variable. It can be derived from the computed velocity field, which is why it is not provided as a visualized result. If you need it, export the velocity results and calculate it yourself. The theoretical background of the depth-averaged equations is covered in iRIC Academy.

Some difference between the imported geographic data and the elevation after the run is expected: when elevation is mapped to the grid it is interpolated, so a small change appears even for a flow-only calculation. If the difference is large, it may be a comparison issue rather than a solver problem. Check that you are comparing the bed profile at exactly the same cross section before and after the run, since selecting a different section in the post-processing window can make it look as if the bed changed. If the discrepancy still cannot be explained, sharing the project file (.ipro) on the forum allows the settings to be checked.

Roughness is mapped from polygon data, and the mapping follows the order of the polygons in the Object Browser on the left side of the window: the polygon listed higher has priority. To assign a base value plus local exceptions:

1. Under Geographic Data > Manning's roughness, create one polygon that covers the entire calculation domain and give it the base value (e.g. 0.012).
2. Create additional polygons only over the special areas (e.g. the vegetation patch with 0.05).
3. Make sure the special polygons are placed above the base polygon in the Object Browser.
4. Run Grid > Attribute mapping again.

If the base polygon sits above the local polygons, its value overrides them, which explains unexpected values after mapping.

iRIC has no built-in generator specifically for bend channels, so the grid has to be built manually. A practical route is a grid generator that lets you draw the channel centre line yourself, such as "Create grid from polygonal line and width" or the multifunction grid generator: place the centre line vertices along the bend and specify the width and the number of divisions. A Japanese-language video on the iRIC site (https://www.youtube.com/watch?v=v_90c11lP24) shows this kind of manual grid construction for a confluence; the same method works for a single meandering or bend channel.

The numerical scheme is not described in detail in the solver manual. Reference material by the solver developer is available on the iRIC site: the online lecture notes at https://i-ric.org/yasu/master_e/index.htm and the collection of PDF documents at https://i-ric.org/yasu/pdf_files/pdf.htm cover the discretization used in the Nays family of solvers. The theoretical background of the numerical methods is covered in iRIC Academy.

The tmp folder created in the project directory is not filled automatically. To produce the files needed for a hot start, first run a calculation with the option "Output temporary files" set to Yes in the calculation conditions and specify the folder path where the temporary files should be written. After that run finishes, the files will be in the folder you specified, and you can point the hot start setting to that path for a subsequent run.

In a reported case this was not related to the solver or the data but to the display setup. With two monitors (a laptop screen plus an external display), opening the 2D post-processing window while the iRIC main window was on the secondary monitor froze the program, whereas opening it with iRIC on the primary monitor worked normally. A likely underlying cause is that the PC has two graphics adapters (e.g. integrated Intel and a discrete GPU) and Windows assigns different adapters to different screens. You can try moving the iRIC window to the primary monitor before opening the visualization window, or set iRIC to use a specific GPU in Windows Settings > System > Display > Graphics settings.

Importing elevation data is not enough by itself; the values must also be transferred to the grid. After creating the grid, run Grid > Attribute mapping so that the imported elevation is mapped to the grid nodes, and check in the pre-processing window that the grid now has elevation values. Running the solver with unmapped grid attributes typically triggers this kind of warning. The iRIC tutorials contain several examples of the mapping step.

The developer framework in iRIC is for registering your own solver; it does not let you plug new modules into an existing solver from outside. Changing the turbulence closure of Nays2DH requires modifying the solver source code, so the advice is to contact the developer of that solver. Note that several solvers already offer more than one turbulence model in their calculation conditions, which may cover your need. A future iRIC version with coupling capabilities between solvers was mentioned as being under testing at the time, but no release details were given.

Rather than repairing the intersections manually, regenerate the grid with a different algorithm. "Create grid from polygonal line and width" tends to produce cleaner grids when the river centre line from the survey data is irregular, because you draw the grid centre line yourself, independent of the river survey centre line, and specify the width. The procedure is described in the iRIC GUI user manual: https://iric-gui-user-manual.readthedocs.io/en/latest/04/05/01_02_polygonal_line_and_width.html. After creating the grid, map the elevation data to it with Grid > Attribute mapping.

No. Nays2DH has no rainfall input; rainfall (including X-band radar data) is a feature of Nays2DFlood only. If rainfall on the computational domain is important for your case, use Nays2DFlood, or represent the additional water as inflow discharge at the boundaries in Nays2DH.

"Calculation failure" is most often caused by an unsuitable combination of the time step (dt) and the grid cell size. Reduce the time step in Calculation Condition > Time and Iteration, or use a coarser grid with wider cells, so that the flow does not cross more than one cell per time step. Trying a smaller dt first is the simplest fix; if the run still fails, also check the initial discharge and the bed elevation for abrupt jumps.

The importable geographic data formats are listed in the iRIC GUI user manual: https://iric-gui-user-manual.readthedocs.io/en/latest/06_files.html. For bathymetry, the common choices are river survey data (.riv), point elevation data (.tpo, X Y Z text) and CSV point files. Convert your survey output to one of these, import it via Geographic Data > Elevation > Import, and then map it to the grid with Grid > Attribute mapping.

This message means the computation is diverging, so the grid and the calculation conditions need to be reviewed rather than the solver itself. Points to check:

• CFL condition: the product of the time step and the flow velocity must be smaller than the grid cell size. If in doubt, reduce the time step first.
• Grid quality: a large size ratio between neighbouring cells makes the calculation unstable, and flipped (inverted) cells, which typically appear in sharp bends, can stop the run. Enable the checks under Option > Preferences > Grid Checking in iRIC to detect such cells.
• Initial and boundary conditions: make sure the discharge and downstream water-surface settings are consistent with the terrain; a failure in the recession limb of a non-uniform hydrograph is also usually a time-step / CFL problem rather than a hydrograph problem.

The iRIC help FAQ page lists further tips for runs that do not proceed smoothly.

Internet background maps are configured in the iRIC pre-processor, not in the Nays2DH solver settings. In the Object Browser there is a Background Images (Internet) item where you can choose the map source to display behind the grid. The available services and how to switch between them are described in the iRIC GUI user manual, section "Object Browser > Background images (Internet)" (iric-gui-user-manual.readthedocs.io). If the Google tiles show a "For development purposes only" watermark, try one of the other map sources offered there.

• Obstacle blocks both the flow and the sediment transport completely in that cell. It can be placed anywhere in the computational domain as a cell attribute, but its size is determined by the grid: an obstacle occupies whole cells, so make the grid fine enough to represent the shape you need.
• Fixed bed (non-erodible bed) represents a surface such as concrete. Sediment can still deposit on top of it, but the cell itself is never eroded.

Both are set as cell conditions on the grid in the pre-processor.

Yes. Nays2DH is a suitable solver for braided-channel development. Unlike the meander examples in the manuals, start from a fairly straight, wide channel with bed deformation enabled and let the bars and multiple channels develop during the run. An example of braided-channel modelling with Nays2DH is available as a video on the iRIC YouTube channel.

An access violation during the run normally means the solver is reading invalid grid information. Review the following settings and correct anything inconsistent:

• the confluence (tributary) settings if the grid includes a confluence (for example a Type A confluence from the left bank);
• the mixed (non-uniform) grain size settings;
• the mapping of geographic data (elevation, roughness, etc.) onto the grid.

The same item is listed in the iRIC help FAQ ("When the calculation stops during the calculation (access violation is displayed)").