Package: raspy-cal
Raspy-CalPython automatic calibrator for HEC-RAS.  RAS + Python + Calibrator = Raspy-Cal.Quick Start GuideYou must have HEC-RAS 5.0.7 installed for Raspy-Cal to work.  Support for HEC-RAS 6 will be added in the future.If you have Python 3 and pip installed, install withpip install raspy-cal.  Otherwise, download the latest executable from Releases.  The Python/pip approach is preferable, as it launches faster and is usually more up-to-date.If installed with pip, run Raspy-Cal withpython -m raspy_cal.  Otherwise, run the executable.  Note thsat the executable will take some time to launch.To load in a configuration file or specify a configuration file to save settings to, set the "Config File Path (optional)" field, for example to the location of Demo/demo_proj.conf if you are using the demo project.To load the configuration data, click "Load Config".Fill out the applicable fields below."Project File Path" should be your HEC-RAS project file.If you are using a USGS gage, enter its gage number.Enter the HEC-RAS river name of the calibration location.Enter the HEC-RAS reach name of the calibration location.Enter the HEC-RAS river station of the calibration location.If you are not using a USGS gage, enter the location of the stage (empirical data) file, e.g. DemoStage.csv.  This should have columns "Flow" and "Stage", in cfs/ft for US units or cms/m for SI units.Enter the slope to use for normal depth as a downstream boundary condition.Enter the flow file number to overwrite in the HEC-RAS project with the flow data. If it is in the single digits, it should have a leading 0 (e.g. "05").Enter how many roughness coefficients to test at once for interactive calibration.Enter the output file path (a .csv file).  In addition to e.g. "DemoOut.csv", which will contain the roughness coefficients and error metrics, Raspy-Cal will also write e.g. "DemoOut-data.csv", containing the model output data for the optimal solutions, and "DemoOut.png", containing the rating curve plot.Select the desired error metrics, whether to display the plot, whether to use datum adjustment, and whether to use SI units. (If SI units are selected, Raspy-Cal will convert USGS data to SI but will otherwise only change the displayed units in plots etc.  The HEC-RAS project and stage file are assumed to be in the correct unit system).Click "Save Config" to save your settings.Click "Automatic Calibration" or "Interactive Calibration".For automatic calibration:Enter the number of evaluations to run.Click "Run Automatic Calibration".  When calibration is complete, Raspy-Cal will display the rating curve plot.  After you close the plot, it will display the error metrics.For interactive calibration:Enter the minimum roughness coefficient.Enter the maximum roughness coefficient.Select whether to use a random or evenly-distributed roughness coefficient distribution.Click "Run Simulations".When the simulations are complete, Raspy-Cal will display the rating curve plot and error metrics. You can either save the results or adjust the roughness coefficient range and run it again.After calibration is complete, results will be saved to the specified output files.  The roughness coefficient set in the HEC-RAS project may not be the optimal result, as the optimal result may not have been the last simulation run.Usage & InstallationWindows ExecutableNote that the preferred method of running, if you have Python 3 installed or are willing to install it, is to download Raspy-Cal from PyPI (seeInstallation).  In addition to launching much faster, this version gets every update, whereas the executable is only updated for more major updates.Downloadraspy-cal.exefrom Releases and run it.  The executable should work without any dependencies.  Note that it will take quite some time to start up as it loads libraries; it is not frozen.  The current version assumes HEC-RAS 5.0.7.  This will be made flexible in a future release.GeneralThe stage (empirical data) file requested must be a CSV with columns named Flow and Stage.  Alternatively, the user can specify a USGS gage to automatically retrieve data.The user must have a HEC-RAS project including appropriate geometry, plan, and an empty flow file, where the plan is set up to use the flow file, in addition to providing empirical data or a USGS gage number (from which empirical data will be retrieved).  The flow data will be generated from the provided or retrieved empirical data as long as a flow file is available and the plan is set up to use it. The flow file does not have to be empty, but the selected one will be overwritten.  Seedevelopment progressbelow.The bulk of the internals are unit system-agnostic, and Raspy-Cal does not check the units of the stage file or the HEC-RAS project; these must be set appropriately, and to match, by the user (cms/m or cfs/ft).  The SI units setting determines data and graph labels (e.g. "Flow (cms)" vs "Flow (cfs)"), and, if the unit system is set to SI, Raspy-Cal will convert USGS data to SI.  The demo project is in SI units.Note that CSVs written by Excel sometimes have special characters in the column headers, which need to be removed in order for the stage file parser to work correctly.Command-Line UsageIf installed with PyPI or running from source, usepython -m raspy_calto launch.  Use the argumentCMDfor text-based interactive use, or pass a config file path as an argument to load the configuration file into the command line version.DependenciesSome Model object which supports the required functionality as describedbelow.  The raspy package, which provides such an API, is
included as a submodule.  The raspy API can be accessed throughdefault.Modelif raspy is somewhere where it can be accessed (e.g. in its subdirectory
as a submodule).  The default installation includes, and uses, raspy-auto, which is the raspy package on PyPI.  All dependencies will be installed automatically if
Raspy-Cal is installed through PyPI.Packages:scipyHydroErrmatplotlibplatypus-opt (NSGA-II implementation)raspy-autoRaspy-cal is only tested with Python 3.  It may or may not work with Python 2.InstallationThis section is not relevant for the executable version.  The executable version is standalone, requiring only that HEC-RAS is installed.Runpip install raspy-calto install via PyPI, in which casepython -m raspy_calwill run the GUI.git clone https://github.com/quantum-dan/raspy-cal raspy_cal(clone intoraspy_calif you want to import it from elsewhere, asraspy-calisn't a valid Python name).The following will install all dependencies and run raspy-cal (with the GUI) using raspy for HEC-RAS access:git clone https://github.com/quantum-dan/raspy-cal
pip install --user scipy HydroErr matplotlib platypus-opt
cd raspy-cal
python main.pyBuilding a Standalone ExecutableRequires pyinstaller (pip install pyinstaller).From the raspy-cal directory, run:pyinstaller -F main.py.  This will build a standalone executable in thedistsubdirectory (which will be created).Functionality & ApproachPaperA full description of the implementation is provided in theassociated paper.General FunctionalityRaspy-cal supports both fully-automatic and partially-manual calibration modes.In manual mode, the user specifies a range of calibration parameters and a set of criteria.  The program runs a specified number of simulations across the range of parameters, comparing the results of each to the relevant criteria.  Then, it shows the user comparison plots (rating curves) of the topnparameter sets based on the criteria.  The user uses that information to specify a new range, and repeat
until the user is satisfied with the results.In automatic mode, the user also specifies a range of calibration parameters and a set of criteria.  Then, the program uses a multi-objective genetic algorithm (NSGA-II with possible future support for other algorithms) to optimize for a specified number of generations with a specified number of tests per generation.  After running the last generation, the non-dominated results are displayed as in manual mode, as well as a plot showing the comparison plots for all of the non-dominated results.  This allows the user to select the overall best choice.In both cases, the user currently has to specify a particular range to calibrate and calibrate against just one empirical data set.  Later, the program will support many data sets covering different ranges.Detailed ApproachTop-level (user-facing) functionality:Display rating curves with parameters and criteriaAccept criteria and parameter ranges and specificationsAccept empirical dataMid-level (doing the work) functionality:Compute criteriaChoose parameter combinationsSelect best combinationsUse automatic optimizationLow-level (support) functionality:Run simulationsUpdate parameter values(Eventually) generate flow profiles etc from empirical data; at first, the user will need to specify the flow profiles (pyRasFile supports this use case with minor manual intervention)Required APIRaspy-cal assumes that the following functionality is available in an API object.  This is provided by Raspy, but an alternative automation API can be provided by modifyingdefault.py; as long as the provided API object has all of the methods detailed below (see Raspy for a reference implementation), no other modifications should be required.  At the current development level, the user must provide an initialized API object with a project open and the appropriate plan, flow, geometry etc selected.For example, having access to the method "api.ops.compute(steady, plan)" would be written as:apiopscompute(steady, plan)Required methods:api: overarching API object containing all functionalityops: general operationsopenProject(projectPath): open the relevant project (project path including *.prj file)compute(steady = True, plan = None, wait = True): compute for the relevant plan, if specified.  If wait is true, don't continue until the computation is done.  Note that the current (prototype) implementation of raspy ignores both arguments and just runs the current plan.data: data retrieval from the latest simulation.  Unless otherwise noted, all the methods work the same way with specifying locations and profiles as allFlow (see below).allFlow(river = None, reach = None, rs = None, nprofs = 1): returns all flow data for the specified location (or, if unspecified, nested dictionaries to the point that it is specified--all None would be{river: {reach: {rs: }}}).  Flow data entries have values .velocity, .flow, .maxDepth, and .etc, where etc is a dictionary of everything else.  If nprofs is 1, it will return that for the first profile.  If not, it will return a dictionary of{profile number: results}for each profile up to nprofs wrapping the aforementioned results.getSingleDatum(func, river, reach, rs, nprofs = 1): like allFlow, but without default arguments andfuncspecifies which aspect to extract (e.g.lambda x: x.velocity).  This is mainly in raspy for internal use (hence lack of default arguments), but may be needed to extract values not automatically provided.velocity(river = None, reach = None, rs = None, nprofs = 1): returns the velocity.stage(river = None, reach = None, rs = None): returns the maximum depthparams: setting parametersmodifyN(manning, river, reach, geom = None): set Manning's n for the given geometry file (if specified).  Note that the current implementation of raspy ignores the geom argument and just uses the current geometry file.  At least the following forms ofmanningmust be supported (note: in raspy currently, setting the "main channel n" actually sets all three ns to the same value):manningis a...list:of lists of numbers: for each cross section (from the bottom), set the ns going from left to right to those provided in the corresponding list.of numbers: for each cross section, set the main channel n to the corresponding value from the list.dictionary ({rs: [...]): set ns by cross section specifically.  The values can be either numbers or lists of numbers, which works the same as the list version above.number: set all the main channel ns to the specified value.setSteadyFlows(river, reach, rs, flows, slope, fileN, hecVer): set the steady flows at that location (or the top cross-section if rs is None).flowsis a list of flows.rscan be None, in which case it will use the uppermost river station in the reach.slopeis the slope for normal depth as a boundary condition.fileNis the flow file number as a string (e.g. "01").hecVeris the HEC-RAS version, and must be optional.