[general]
name=aXqua
qgisMinimumVersion=3.44
qgisMaximumVersion=4.99
description=Set up, run and monitor TELEMAC and OpenFOAM models of free-surface water bodies (rivers, lakes, reservoirs, hydraulic structures) from QGIS, with jobs that keep running after QGIS is closed.
about=aXqua turns geodata into a calibration-ready hydro- and morphodynamic model (TELEMAC-2D/3D with GAIA, or an OpenFOAM interFoam free-surface case) and drives it through a persistent job runner. Simulations are launched as detached system jobs, so they survive closing QGIS, and are rediscovered with their live state when you reopen it. Results load back as mesh, raster and vector layers, with depth and velocity styling applied to the meshes. The plugin drives the aXqua command-line tool, installed separately with 'pip install axqua', and needs a working TELEMAC and/or OpenFOAM installation.
version=1.3.5
author=Sebastian Schwindt
email=schwindt.water@gmail.com

tracker=https://github.com/sschwindt/aXqua/issues
repository=https://github.com/sschwindt/aXqua
homepage=https://axqua.eu

# The plugin itself is GPLv2+ because it links PyQGIS. The axqua package it
# drives stays BSD-3-Clause, which is GPL-compatible, and remains usable on its own.
license=GPL-2.0-or-later

category=Plugins
icon=resources/axqua.png
tags=hydraulics,hydrodynamics,telemac,openfoam,cfd,river,lake,reservoir,hydraulic structures,mesh,simulation,calibration,morphodynamics

experimental=False
deprecated=False
server=False
hasProcessingProvider=yes

changelog=1.3.5
    - TELEMAC built in Windows itself is built for parallel runs (MPI) by
      default; the one-core build stays a choice of the Setup Wizard
      (--one-core in a terminal).
    - The measured velocity of a vertical is compared with the 2D model
      at 0.6 of the water depth above the riverbed. Where a vertical has
      several readings around that height, aXqua fits a logarithmic
      velocity profile to them and reads the velocity at that height off
      the profile; any other vertical is represented by its reading nearest
      that height, moved there along a logarithmic profile with the
      roughness of its own readings or of the same survey. This is the new
      default of a measurement file (profile rule log-profile).
    1.3.4
    - Calibration: a roughness zone without a calibration point is no
      longer calibrated, and a zone whose measured water is shallower than
      its largest ks gets that depth as its largest ks. Submit on the tab
      Calibration and validation asks first: calibrate only the zones with
      data, or abort and see the zones and the points in QGIS.
      'axqua calibration <case>' lists the zones in a terminal.
    - The calibrated values are the peaks of each parameter's own
      posterior (per-parameter maxima), also in the validation.
    - After a calibration, aXqua writes a report: the posterior of each
      zone, a map of the zones with their ks, the evidence over the
      iterations, and a zones layer that Load results shows labeled.
    - A Colebrook-White friction zone is written with TELEMAC's law 6 and
      its Manning column.
    - HydroBayesCal 1.13.0 or newer is required:
      'pip install -U hydrobayescal'.
    - Windows: the Setup Wizard offers an optional parallel TELEMAC build
      in Windows itself (MS-MPI and METIS, no administrator rights); one
      processor core stays the default.
    - 'axqua status <job folder>' shows the job instead of an error.
    1.3.3
    - Calibration at several discharges: 'calibration.situations' names
      surveys measured at other discharges, each with its measurements and
      its discharge. Every tested set of parameters is simulated at each
      discharge, and HydroBayesCal fits one set to all of them. In the case
      settings, a file of the table Measurement files used for Calibration
      gets a situation name and its discharge.
    - 'calibration.hotstart: true' starts every calibration run from the
      steady result instead of the dry or pre-wetted start; each run lasts
      1.2 residence times of the reach unless 'hotstart_duration' says
      otherwise.
    - 'calibration.structural_error: unreachable' adds to the error of a
      point the misfit that no tested set of parameters removes, so a point
      the model cannot reproduce no longer decides the calibration alone.
    - HydroBayesCal 1.12.2 or newer is required, also in an environment
      that had an older one: 'pip install -U hydrobayescal'.
    - Upgrade the program with 'pip install --upgrade "axqua[calibration]"'.
    1.3.2
    - Windows: QGIS, the plugin and aXqua run in Windows. Without WSL, the
      Setup Wizard builds TELEMAC as a Windows program in the user folder,
      with no administrator rights; it runs on one processor core. With WSL
      set up by an administrator, the Setup Wizard installs TELEMAC and
      OpenFOAM inside WSL (tested with a stand-in for WSL only).
    - Windows: the variables of QGIS's own Python no longer reach aXqua, and
      user folders with umlauts, spaces or another code page work. Help opens
      the English pages by default (aXqua > Settings), and questions have
      English buttons.
    - A job runs with the number of processes set for it. On a TELEMAC
      without MPI a job runs on one process, with a warning in the message
      bar; a larger number asked for with the job is refused before it
      starts. Cancel ends TELEMAC and every process it started, also on
      Windows.
    - Report issue names the error of a failed check and hides the home
      folder however it is written.
    - After a restart of QGIS, the tabs show the active case without Refresh.
    - Upgrade the program with 'pip install --upgrade "axqua[calibration]"'.
    1.3.1
    - Measurement points less than 15 mesh nodes from an inflow or outflow
      line are left out of the calibration, the validation and the mesh
      convergence study. A warning names them and the boundary, with the
      remedy "Increase ROI beyond the concerned liquid boundary."; the plugin
      shows it when the results of the job are loaded.
    - TELEMAC-3D can use a horizontal mesh of its own: 'mesh.size_scale_3d'
      (Factor on all edge lengths in 3D). A 3D run costs much more per cell,
      so the 3D model often gets a coarser mesh than the 2D model. aXqua
      builds it in axqua-case/simulation-3d/ and starts the 3D runs from the
      steady 2D result interpolated onto it.
    - Upgrade the program with 'pip install --upgrade "axqua[calibration]"'.
    1.3.0
    - TELEMAC-2D chooses the turbulence model in a new way. A depth-averaged
      model cannot resolve eddies smaller than the water depth, so aXqua
      compares the filter width of the channel cells (the square root of twice
      their area) with the flow depth. Where the cells are wider than the
      depth, it selects the k-epsilon model; where they are not, the Smagorinsky
      model of large eddy simulation, with the turbulence generated at the bed
      added by a routine aXqua writes into user_fortran/smagor.f.
      Spalart-Allmaras is no longer selected automatically, and aXqua warns
      when a case names it for a reach wider than about ten depths (it suits
      flumes). Cases with 'turbulence_model: auto' give different results.
    - The k-epsilon model runs on a bed that wets and dries: aXqua solves it
      with GMRES and writes user_fortran/corvis.f, which holds the model at
      rest on nodes shallower than 2 cm and bounds its length scale by the
      depth. On the Inn KB15 case, six meshes ran without a failed solve.
    - Mesh convergence study: compares the mean over the second half of each
      run instead of the last frame, reports how much the values fluctuate in
      time, and says when the last change is smaller than that fluctuation.
      No point lies close to the inflow or outflow line: the points keep four
      flow adaptation lengths (Struiksma et al. 1985) from both, 190 m on the
      Inn KB15 case, where the inflow had decided the verdict. Measurement
      positions closer to the lines are left out. A ground-truth table of an
      earlier build is no longer used once the case names no ground truth.
    - Calibration requires HydroBayesCal 1.11.0 or newer: older versions stop
      when a measurement point is dry in every run. A build made after a
      cancelled calibration is no longer replaced by the previous build.
    - Isar example: k-epsilon, 6000 s simulated time, guide updated.
    - Upgrade the program with 'pip install --upgrade "axqua[calibration]"'.
    1.2.2
    - Mesh convergence study (TELEMAC): each mesh is read on its own
      double-precision geometry. TELEMAC stores the coordinates of a result in
      single precision, which at UTM coordinates resolves only 0.5 m; the report
      gave wrong shortest edges and time steps for fine meshes and moved the
      values at the points by up to 1.6 percent.
    - Vertical convergence study (TELEMAC-3D): no longer diverges at its first
      time step. In 3D, aXqua uses k-epsilon in place of the automatically chosen
      Spalart-Allmaras model, which fails on a bed that wets and dries unless
      the case has its source-term patch in user_fortran/. This also applies to
      the Steady 3D and Unsteady 3D runs.
    - Vertical convergence study: compares the mean over the second half of each
      run (20 result frames per run) instead of the last frame, and reports how
      much the values at the points fluctuate in time. Near bars the 3D flow does
      not become fully steady.
    - Both studies draw a figure (value at each point per mesh, mean against
      cell size, change per refinement against the tolerance) and add the sheet
      'values at the points' to the workbook.
    - The fixes are in the aXqua program: upgrade it with
      'pip install --upgrade axqua'.
    1.2.1
    - Hydrology mode: the sediment budget of a run on several processor cores
      is right. TELEMAC v9.1.1 writes into each processor's listing only the
      suspended sediment that left through its own part of the mesh; aXqua now
      adds the listings of all processors. Eroded and deposited mass come from
      GAIA's erosion and deposition fluxes. aXqua 1.2.0 counted the sediment that
      left through the other parts as deposited.
    - The fix is in the aXqua program: upgrade it with
      'pip install --upgrade axqua'.
    1.2.0
    - Setup Wizard for TELEMAC and OpenFOAM on the Configuration tab: select an
      existing environment script, which aXqua checks module by module (a valid
      installation that lacks GAIA, TELEMAC-3D or sediDriftFoam2 is told apart
      from an invalid one), or install the program.
    - Hydrology mode: sediment transport with GAIA, strongly recommended, with the
      Sediment transport wizard (soil layer, grain sizes, a recommendation after
      van Rijn and Partheniades for the soil and the slope) and a sediment budget
      of the run. The checkup refuses sediment setups that TELEMAC cannot run
      where a river flows into the model.
    - Hydrology mode: optional river lines, an inflow line with the discharge of a
      river and its outflow line with an outlet of its own (data wizard, tab
      River).
    - The example example-agrohydrology transports sediment.
    - Steering files keep every line within the 72 columns TELEMAC reads.
    - Needs the aXqua program 1.2.
    1.1.1
    - Load results: the layers "infiltrated depth" and "high water mark" of a
      hydrology run showed the water depth of the first time step. Each now shows
      its own variable, and the high water mark is drawn as the highest water
      depth (the mark minus the bed). Results of aXqua 1.1.0 are read too.
    - The aXqua program is published on PyPI by the release workflow.
    1.1.0
    - Hydrology mode: rainfall-runoff over a catchment or a field with TELEMAC-2D
      and Green-Ampt infiltration, rain uniform in space, wind and evaporation.
      The sub-tab Simulations > Hydrology runs it, a data wizard fetches or reads
      rain, soil, initial moisture, wind and sun, and a checkup of the data and of
      the terrain runs before the build.
    - A second example case, example-agrohydrology: an arable field in Lower
      Bavaria under a storm of 42 mm in 7 hours.
    - The plugin passes the Qt6 check of the QGIS plugin repository.
    - The plugin needs the aXqua program 1.1 or newer. Upgrade it with
      'pip install --upgrade axqua'.
    1.0.2
    - The inflow of a model received no discharge when the south-westernmost node
      of its outline was the last node of a liquid boundary line: TELEMAC then
      numbers that line last, and the discharge went to the outflow. The numbering
      of aXqua now follows TELEMAC in this case too. Rebuild a model that was built
      with an earlier version.
    - The gauge tool (scripts/gauge_data.py) keeps the fetched gauge when a table
      is downloaded, so the hydrograph and the rating curve can be saved one after
      the other.
    1.0.1
    - The aXqua program is published on PyPI. Install it with 'pip install axqua'
      and upgrade it with 'pip install --upgrade axqua'; Git and a copy of the
      repository are no longer needed.
    1.0.0
    - The first stable release. It needs the aXqua program 1.0 or newer.
    - Documentation in English, German and French at https://axqua.eu. Help opens
      a copy built on this computer when there is one, else the published pages,
      in the language of QGIS.
    - Clean Up, left of Help, removes what a case no longer needs: working folders
      of interrupted runs, listings, earlier time steps of results, processor
      folders of reconstructed OpenFOAM runs and exports. Inputs, the case file,
      the built model and the last time step of a result are never offered, and
      nothing is removed while a run may still use it.
    - One Simulations tab with Baseline (Telemac), OpenFOAM, Mesh convergence and
      Morphodynamics, and a mesh convergence study for OpenFOAM.
    - Case settings replace the project file: the cases are kept in the QGIS
      settings, required entries are marked, and a table lists the measurements
      for calibration and validation.
    - The outlet of an OpenFOAM model can follow a stage-discharge relation (the
      boundary condition of BAW).
    - OpenFOAM runs on any number of processes; the results of an earlier run are
      set aside in previous-run instead of being deleted.
    - Calibration against the targets of the case file, water depth and velocity.
    - The installation wizards are tabs, run the fixes they ask for, and install
      again on request.
    0.5.0
    - Installation wizards for TELEMAC, OpenFOAM with the sediment solvers, ParaView
      and VisIt, for you alone or for all users of the computer.
    - The OpenFOAM installation no longer depends on the website of the sediment
      solvers: their source code ships with aXqua.
    - A profile per computer names where the programs are installed; a case file
      (.axq-case) describes the reach. The profile editor and the case editor edit
      them, and a check reports everything that is not in order at once.
    - The panel follows the workflow: Configuration, Case Setup, Preprocessing,
      Hydraulic simulation, Morphodynamic simulation, Calibration and validation,
      Postprocessing, Batch-processing, each with its Help page.
    - Jobs of a case run one after the other and keep running when QGIS is closed.
    - Validation of a calibrated model against measurements of another flow
      situation.
    - Fine sediment over a bed that stays in place, simulated with OpenFOAM.
    - Results export to ParaView and VisIt; a loaded result shows its last time
      step.
    - The Isar example case downloads with its data and a step-by-step guide.
    - Export movie is in the aXqua menu, and QGIS stays responsive while aXqua
      works.
    - Errors show what aXqua said and what to do about it.
    0.2.0
    - First release.
    - Persistent job runner: submit, monitor and cancel TELEMAC/OpenFOAM runs that
      outlive the QGIS session.
    - Job dashboard with adaptive polling, rediscovery from a .axqua-prj project.
    - Tabs generated from axqua's capability matrix, so a case only offers what it
      can actually do.
    - Result loading with depth and velocity styling, plus an A3 print layout.
    - Processing algorithms that submit and return rather than blocking QGIS.
