IFAS Calibrator Version 2.0
User Manual

ICHARM(The International Centre for Water Hazard and Risk Management)
Public Works Research InstituteTable of Contents
1. Introduction ........................................................... 1
1.1 About IFAS Calibrator .................................................. 1
1.2 Operating System Requirements .......................................... 1
1.3 Installation of Microsoft .NET Framework ............................... 1
2. IFAS Calibrator Installation ........................................... 4
3. Parameter Optimization Settings ........................................ 5
3.1 Setup .................................................................. 5
3.2 IFAS Calibrator Startup ................................................ 6
3.3 Opening an Optimized Target Model from IFAS Projects ................... 7
3.4 Optimized Target Simulation Selection .................................. 9
3.5 Setting the Optimization Scope ........................................ 10
3.6 Setting the Optimization Evaluation Period ............................ 14
3.7 Setting the Observation Point ......................................... 15
3.8 Multiple Target Optimization Settings ................................. 17
3.9 Configuring Optimization Algorithms ................................... 18
3.10 Setting the Result Folder ............................................. 22
4. Optimization Execution ................................................ 23
5. Verification of Optimization Results .................................. 24
5.1 Loading the Optimized Results ......................................... 24
5.2 Verification of Error Graph and Hydrograph ............................ 26
5.3 Confirmation of Pareto chart .......................................... 28
5.4 Analysis of Optimization Results ...................................... 36
6. Loading Previous Optimization Settings ................................ 38
7. Troubleshooting ....................................................... 40
A) Data of the observation flow rate mismatch ............................ 40
B) Divergence of IFAS .................................................... 40
C) Divergence of error value evaluation of optimization .................. 40

1.

Introduction

1.1

About IFAS Calibrator
IFAS Calibrator is a tool that optimizes parameters of the IFAS (Integrated Flood Analysis
System) using the observed flow rate. The simulation can be run once an IFAS project is created.
The optimization of an IFAS project is limited to a two-layer tank model.

1.2

Operating System Requirements
OS：Windows7/8.1/10 (32bit/64bit)
CPU：at least 2GHz
Memory： at least 2GB of RAM
Required software：.NET Framework 4.6 or greater

1.3

Installation of Microsoft .NET Framework
IFAS Calibrator requires .Net Framework to operate, installation instructions are provided
below:① Download .Net Framework from Microsoft’s software download portal.

IFAS Calibrator Version 2.0 User Manual

1

② Execute the downloaded file.
Depending on the security settings in place, a dialog similar to that shown below may
appear. If this dialog appears, press “Yes”.

③ Execute the installer and follow the provided prompts.

dIFAS Calibrator Version 2.0 User Manual2

IFAS Calibrator Version 2.0 User Manual3

2.

IFAS Calibrator Installation
Do not use the IFAS Calibrator installer. Installation involves uncompressing the IFAS
Calibrator archive into any location.

The path of where IFAS Calibrator was

uncompressed must not contain Japanese characters (ex. C:∖).

IFAS Calibrator Version 2.0 User Manual4

3.

Parameter Optimization Settings

3.1

Setup
Load a simulation from an IFAS project file.
NOTE: An optimized IFAS project is limited to a two-layer tank model.

IFAS Calibrator Version 2.0 User Manual

5

3.2

IFAS Calibrator Startup
Double click on “IFASCalibrator.exe” in the location of the extracted archive file.

After the program opens, click “Calibration(C)” from the menu bar, and the interface forchoosing settings will appear.

IFAS Calibrator Version 2.0 User Manual

6

3.3

Opening an Optimized Target Model from IFAS Projects
In the “Target Model” section, from the IFAS Project field, clicking the “Select” button
will display a folder selection dialog.

IFAS Calibrator Version 2.0 User Manual7

After the folder selection dialog is displayed, select the desired IFAS project folder byclicking on it.

After selecting an IFAS project folder and pressing the “OK” button, project details, suchas the Simulation Model name and Simulation period, will be displayed.

IFAS Calibrator Version 2.0 User Manual

8

3.4

Optimized Target Simulation Selection
If there are multiple Simulation Models in the imported IFAS project, select the desired
optimization target from the dropdown menu in the Simulation Model field.

IFAS Calibrator Version 2.0 User Manual

9

3.5

Setting the Optimization Scope
Click the “Select Parameter” button from the Parameter field.

IFAS Calibrator Version 2.0 User Manual

10

IFAS parameters are enabled by clicking the respective check box in the “Enable” field.
Minimum, maximum, and initial values can also be set for the optimization target. Clickthe “OK” button to set parameters.
“Enable”, “Min”, and “Max” are automatically set to default values, verify if any changes
are necessary. “Initial Value” contains the values used in the selected IFAS simulation.
Change values as necessary.
An error check will be performed for the values that you set, and an error message will
be displayed for cells in error. Cells in red indicate an error. For an overview of error
checking, see P12. Error checking is performed when the screen is opened. Therefore,
when opening the screen for the first time, Min and Max may show error with the default
values and the values used in the IFAS simulation.

IFAS Calibrator Version 2.0 User Manual

11＜Error checking outline＞
・All parameters must have Min<=Initial Value＜Max.
・Part one parameters must not be 0 (To prevent division by 0 errors)
・Part one parameters that must be greater or smaller than related variable must haveappropriate values.
NOTE: The error message does not change any values. All values must be changed andconfirmed by the user.
Examples of error messages.

IFAS Calibrator Version 2.0 User Manual

12The “Parameter” field will change to “Configured.” when settings are properly set.

IFAS Calibrator Version 2.0 User Manual

13

3.6

Setting the Optimization Evaluation Period
The optimization evaluation run duration can be shortened.
The dates can be chosen from a drop-down calendar, but time must be directly entered.

IFAS Calibrator Version 2.0 User Manual

14

3.7

Setting the Observation Point
Click the “Add” button in the “Target Point” section to set the observation point for the
optimal flow rate to be used for optimization.

Enter the observation Name, then Cell ID, or the Col and Row of the desired observation
point of the corresponding IFAS project. Click the “Select” button to select the observation
flow data file.

IFAS Calibrator Version 2.0 User Manual

15

The observation flow data file must be in the format as shown below.
NOTE: each line must be “YYYYMMDDhhmm(space or tab)<flowrate>”

201406150000 49.21
201406150100 45.03
201406150200 42.34
201406150300 41.03
201406150400 39.74
201406150500 38.46
201406150600 38.46
Make sure the observed flow files are always in the same interval as the IFAS project
calculation interval for the entire period of the IFAS project to be optimized. The entire
duration of the IFAS project is required, not only the optimization evaluation period.
Also, each line must contain data, there must not be missing data within the time frame.
For example, if the duration of the project is 6/15/2014 00:00 to 6/17/2014 23:00, with acalculation interval of 60 minutes, there must be 24 x 3 = 72 rows all containing data (nomissing values).

IFAS Calibrator Version 2.0 User Manual

16

3.8

Multiple Target Optimization Settings
If multi-point multi-objective observation is desired, click the “Enable multi target” box
to allow multiple points to be enabled. Click the check box in the “Enable” field to enable
the target point.

The weight of error evaluation function for each point that have “Enable” checked can be
set in the field “ErrorWeight”.

Right-clicking the header of the maximum flow rate (MaxDischarge) or the total flow rate
(TotalDischarge) displays a menu where the error weight can be automatically set based on
the maximum flow rate or the total flow rate.

IFAS Calibrator Version 2.0 User Manual

17

3.9

Configuring Optimization Algorithms
Select the desired optimization method.

IFAS Calibrator Version 2.0 User Manual

18The algorithms to choose from are listed below.
SolverAlgorithm

pyopt_sdpen

Sequential Penalty Derivative-free method for Nonlinear
constrained optimization

pyopt_slsqp

Sequential Least Squares Programming

pyopt_psqp

Preconditioned Sequential Quadratic Programming

pyopt_algencan

Augmented Lagrangian with GENCAN

pyopt_filtersd

FILTERSD uses a generalization of Robinson’s method,
globalised by using a filter and trust region.

pyopt_conmin

CONstrained function MINimization

pyopt_ksopt

Kreisselmeier–Steinhauser Optimizer

pyopt_cobyla

Constrained Optimization BY Linear Approximation

pyopt_solvopt

SOLver for local OPTimization problems

pyopt_alpso*

Augmented Lagrangian Particle Swarm Optimizer

pyopt_nsga2*

Non Sorting Genetic Algorithm II(pyopt)

pyopt_alhso

Augmented Lagrangian Harmony Search Optimizer

r_mco_nsga2*

Non-Sorting Genetic Algorithm II(R)*Requires a setting other than the number of calculations.
Detailed descriptions of each pyopt algorithm can be found at the following site:
http://www.pyopt.org/reference/optimizers.html
Detailed description of r_mco_nsga2 can be found at the following site:
https://www.rdocumentation.org/packages/mco/versions/1.0-15.1/topics/nsga2

IFAS Calibrator Version 2.0 User Manual19

Once the algorithm is selected, set the calculation count (Iteration).

If you select a Solver (see P19) that requires a setting other than the number ofcalculations, it will appear as follows:
For pyopt_nsga2 or r_mco_nsga2, set the maximum number of individuals (MaxPopulation) and the maximum number of generations (Max Generation).
maximum number of individuals can only be a multiple of 4.

The

The number ofcalculations will be “Max Population” and “Max Generation”.

For pyopt_alpso, set the number of particles in “SwarmSize” and the number of externalloops in “MaxOuterIter”

IFAS Calibrator Version 2.0 User Manual

20

Set the error evaluation function to use as shown in the figure below.

The three error evaluation function choices are listed below.
𝑛 is the number of calculation steps of the IFAS project to be optimized, 𝑥 is thecalculated flow rate of IFAS in the calculation step 𝑡 , 𝑜 is the observation flow ratein the calculation step 𝑡 .
・Mean square error
𝐸 =(𝑥 − 𝑜 )
𝑛

𝐸 =

𝑥
−1
𝑜

・Relative error

・Log of Mean square error
𝐸 = log

IFAS Calibrator Version 2.0 User Manual(𝑥 − 𝑜 )
𝑛

21

3.10

Setting the Result Folder
Click the “Select” button beside the Result Folder field and the save location for results
will be set.

NOTE: Multi-byte characters must not be used in the path and Result Folder.

IFAS Calibrator Version 2.0 User Manual

22

4.

Optimization Execution
Click the “Execute” button to run the optimization.

After the calculations are saved, the below message will appear.

IFAS Calibrator Version 2.0 User Manual

23

5.

Verification of Optimization Results

5.1

Loading the Optimized Results
From “Result View” in the menu bar, click “Error/Hydro Graph”.

IFAS Calibrator Version 2.0 User Manual24Click the “Select” button and choose the desired Result Folder.

After a folder is selected, “Open Error/ Hydro Graph” button will be displayed on thescreen. If multi target optimization is enabled, the “Open Pareto Chart” button will also
be displayed.

IFAS Calibrator Version 2.0 User Manual

25

5.2

Verification of Error Graph and Hydrograph
Click the “Open Error / Hydro Graph” button to display a graph of the error values foreach trial.
The “Trial Number” list box is sorted in descending order of error value.
By default, the trial number with the smallest error is selected.

IFAS Calibrator Version 2.0 User Manual26

Click the “Hydro Graph” radio button to display a hydrograph of the flow rate in the trial.

IFAS Calibrator Version 2.0 User Manual

27

5.3
Confirmation of Pareto chart
5.3.1 Display Pareto Charts
Click the “Open Pareto Chart” button to display the Pareto chart.
By default, the X and Y axes display the same target points (TargetPoint).
Different target points can be selected from the “TargetPoint” dropdown menu.

IFAS Calibrator Version 2.0 User Manual28

5.3.2 Pareto Chart Zoom
The mouse wheel can be used to zoom in and out of the Pareto chart.
In the figure below, the green point is the minimum error of the “TargetPoint X”. The
yellow point is the minimum error of the “TargetPoint Y”. The red point is the minimum
error when considering the sum of both target points. The pink points are the 10 best points
when considering the sum of both target points.

IFAS Calibrator Version 2.0 User Manual29

5.3.3 Pareto Chart Rectangle Selection
A rectangular area of the Pareto chart can be selected by dragging the mouse.

Theselected area can be zoomed into or deleted.

D
e
l
e
t
e

IFAS Calibrator Version 2.0 User Manual30

5.3.4 Hydrograph Display
Double-clicking a point on the plot will display the hydrograph of the trial times for both
“TargetPoint X”, and “TargetPoint Y”.

IFAS Calibrator Version 2.0 User Manual315.3.5 Plot Filtering
The box on the right side of the screen are parameters for plot filtering.
Plots can be refined and will be displayed in the graph on the left. Plots can be filteredby either evaluation values or parameter range.
The plot points to be deleted will appear in grey.
Entering range values then removing focus of the text box will grey points outside if therange.
Clicking the “Apply” button will delete the points in grey. Clicking “Cancel” will restore
the graph to its original appearance.
Once a deletion is performed by clicking the “Apply” button, the graph cannot be restored
to its original form.

IFAS Calibrator Version 2.0 User Manual325.3.6 Output
After finding the Pareto boundary, by using the filtering and rectangular deletionfunctions, click the “Output CSV” button to save the parameter set, that describes thePareto boundary, to file.
After finding the Pareto boundary, the filtering and rectangular deletion functions can beused to save the parameter set to a file by clicking the “Output CSV” button.

The Pareto boundary can be reproduced by reading in the output file.

IFAS Calibrator Version 2.0 User Manual33

NOTE: Any file in CSV format, where first line is a header and first column containthe trial count, can be loaded.

Keep the plot containing trial numbers that matchthe loaded file and delete all other plots.

(The first line is treated as a header line and is ignored.)879,・・・(The second column is ignored and its contents can be anything.)
902,・・・
909,・・・
957,・・・
989,・・・
1002,・・・

IFAS Calibrator Version 2.0 User Manual34

5.3.7 Support Features
Additionally, the following support functions are provided:
Buttons can be used operate the Pareto Chart when the mouse wheel is unavailable.

：Zoom in

：Zoom out

：Display all (return to initial display)
Rectangular areas can be selected by entering text into the following ranges when themouse drag is unavailable.

IFAS Calibrator Version 2.0 User Manual

35

5.4

Analysis of Optimization Results
From “Result View” in the menu bar, click “Data Analysis” in the drop-down menu.

Click the “Select” button and choose the desired “Result Folder”.

IFAS Calibrator Version 2.0 User Manual36

Click the “Add” button to add the selected folder to the list.
Also, if multiple points have been optimized, the point to be analyzed can be selected fromthe “Display Point” dropdown menu.

In the optimization analysis screen, the observed flow rate and the calculated flow rateof all trials of optimization calculation are displayed. Manipulating the grid below thegraph will narrow down the range of parameters and calculated flow to be displayed. Thisis done for further refinement of the optimization.

IFAS Calibrator Version 2.0 User Manual

37

6.

Loading Previous Optimization Settings
To load previous optimization settings to continue calculations, click the “Open IFAS
Calibrator Setting File” button and select the “IFASCalibrationParam.xml” in the
optimization result folder.

IFAS Calibrator Version 2.0 User Manual38The previous optimization settings are loaded.

IFAS Calibrator Version 2.0 User Manual

39

7.

Troubleshooting
If the following error occurs when performing steps in sections “5.1 Verification ofError/Hydro Graph” and “5.3 Analysis of Optimization Results”, it indicates that the
specified optimization output file cannot be read.

If the file “datafile.txt” exist in the location specified by the message, the following causesof error may exist:A) Data of the observation flow rate mismatch
Ensure that the observed flow file has the same interval as the IFAS project calculationinterval for the entire period of the IFAS project that is being optimized. Please note theentire duration of the IFAS project is required rather than the optimization evaluation
range.

B) Divergence of IFAS
The calculation results diverge, and the optimization process may have ended
prematurely.

In this case, one of the files under the “WORK_OUT” folder in the

optimization results folder contain “nan” values.

Review the search scope of theparameters and perform the optimization again.

C) Divergence of error value evaluation of optimization
For multi-objective optimization, if the weight is large, the evaluation function may
diverge, and the optimization process may have prematurely ended. In this case, reduce
the weighting and perform the optimization again.

IFAS Calibrator Version 2.0 User Manual40