The MultiProc class allows to define and run tasks in parallel. A number of N processing instances (nb_cpu provided, default all cores but one) are created; then tasks from the tasks list are dispatched to the processing instances.

An init task (resp. a term task) may be provided; if so it is called by each processing instance before the 1st task (resp. after the last one). If init is not provided, first N tasks are guaranteed to be run on distinct instances and can also be used for initialisation purposes. Then each task in the list is associated to the next processing instance available in turn. The execution order is not guaranteed (except the first N tasks if init is not provided).

run executes the tasks list in parallel processing instances; run_sequential executes the tasks list sequentially, i.e. init, tasks in order, term.

SYNTAX

mp = MultiProc(logprint [, nb_cpu= -1] [, wait= 0.0] [, use_wpnum= False] [, reduce= NONE] [, progress= NONE])
results, resinit, resterm = mp.run(tasks [, init=NONE] [, term= NONE])
results, resinit, resterm = mp.run_sequential(tasks [, init=NONE] [, term= NONE] [, wpnum= NONE])
comb_results = mp.run(tasks [, init=NONE] [, term= NONE])
comb_results = mp.run_sequential(tasks [, init=NONE] [, term= NONE] [, wpnum= NONE])
ncpu = mp.nmaxcpu

ARGUMENT

function logprint: called by mp.run with a single str arg for logging
int nb_cpu: optional number of parallel processes, up to the hardware core count. A negative value indicates the number of hardware cores + nb_cpu (defaults to -1).
float wait: wait time (s) before the first task of each processing instance.
bool use_wpnum: if True, the function called in task list must accept an integer keyword argument wpnum, being equal to the process number (1 ... nb_cpu) in charge of its execution.
callable progress: function for displaying the overall progression. It is called after every task completion with the completion rank (starting at 0) and the total task count, i.e. progress(i, ntasks) where i in range(ntasks).
callable reduce: function for reducing the simulation results. the first call to 'init' is used to initialise comb_results; then every incoming result is merged in turn (in random order): comb_result = reduce(comb_results, result)
tasks: list of (func, args) tuples defining the tasks to be run as result = func(*args) if use_wpnum is False or not set; or result = func(*args, wpnum= proc_num) otherwise. if func returns a str or unicode, it will be inserted in the log string.
init (optional) tuple (func, args) to be called by every processing instance before any tasks.
term (optional) tuple (func, args) to be called by every processing instance after all tasks.

RESULT

int ncpu: number of processing instances.

When reduce function is not provided:

results: list of result = func(args), in the original tasks list order.
resinit: list of results for init calls (empty if init is NONE). Its length is the processing instances count.
resterm: list of results for term calls (empty if term is NONE). Its length is the processing instances count.

When reduce function is provided:

comb_results: reduced results. Roughly reduce(reduce, results, init_result)

REMARKS

tasks are run in parallel by the set of parallel processes: when a process ends up a task, it starts executing the next task available in the list.
the number of processing instances is available as mp.nmaxcpu
run_sequential is provided for debugging, it loops and execute tasks in turn.
if the tasks count is smaller than the number of requested cpus, the number of processing instances is reduced to the task count.

HISTORY

Created 2016.12.14
Updated 2017.11.14: class interface and optional wpnum argument.
Updated 2017.11.17: renamed to parallel; added results return list. added init and term options
Updated 2017.11.20: return values as a tuple of 3 lists for tasks, init, term
Updated 2017.11.30: added progress method
Updated 2018.04.18: added reduce method; fix init seq run issue.
Updated 2018.05.14: fix python3 issue

4. ganessa.sim&th/About [ Introduction ]

[ Top ] [ Introduction ]

PURPOSE

The module ganessa.sim (resp. ganessa.th) provides a Python interface to Picwin32.dll and Ganessa_SIM.dll (resp. Ganessa_TH.dll) kernels. It will be extended as needed.

The module name ganessa.sim&th is used for items availble both in .sim and .th environments

INSTALLATION

pip install ganessa

numpy must be installed in version >= 1.7; pip will handle it.

The package expects the simulation kernel .dll to be found either in the folders given by %GANESSA_DIR environment variable (for Ganessa_xx.dll) or %PICCOLO_DIR (for Picwin32.dll), or in the %PATH environment variable (either name), or in one of the sub folders of Program Files folder (x86 under Windows 7):

"Safege/Ganessa_<lang>/Ganessa_xx" (xx = SIM or TH) or
"Gfi Progiciels/Piccolo6_<lang>[_ck]/Picwin32.dll" or
"Gfi Progiciels/Picalor6_<lang>[_ck]/Picwin32.dll" or
"Adelior/Piccolo5_<lang>/Picwin32.dll"

in either drive D: or C:

USE

Syntax:

import ganessa.sim as pic (or ganessa.th for Picalor)
pic.cmdfile('my file.dat')

Or:

from ganessa.sim import *
cmdfile('my file.dat')

the import will perform the following initialisation tasks:

locate Ganessa_xx.dll or Picwin32.dll kernel
initialise it
locate result.bin in a working subdirectory
bind termination to ctrl+Z

CONTENT

The package provides the following content:

Constants for calling API functions
iterators for browsing objects and selections
functions for loading .bin file
functions for executing command files / command strings / running simulations
functions for catching simulation errors and retrieving Unstable items
functions for retrieving individual objects attributes
functions for retrieving Table entries and object count
functions for retrieving result or measurements time series
functions for retrieving min / max / avg values for all objects

REMARKS

Most of the functions are getter. A few direct setter functions are provided (setlinkattr, setdensity, defcalind, *SHL functions). The general purpose gencmd(w), addcmd(w), cmd, execute and cmdfile can be used to build / commit any other settings with command language (see the Piccolo Reference Manual).
Commands (passed to cmd, execute, cmdfile) should be built in the language (idiom) of the current version. getkeyword, modulekeyword, attrkeyword allow to retrieve a given keyword in the current idiom; gencmd(w) allow to build a command line in the current idiom.
A command file may be written in any of English, French or Spanish, the current command language interpreter will switch to the xxx language from _LANG_ xxx command until the end of the file, then switch back to the current language.
Any suggestion for extending / improving can be mailed to: piccolo@safege.fr

HISTORY

The history of the package is:

1.0.3: plotmesx png takes care of measurement type
1.0.4: added demand getter for a demand code or for all
1.0.5: added Windows 7 paths 'program files (x86)'; added option to get TS by measurement step 'tsvalbymts'; added 'refdate' : retireval of refdate
1.0.6: correction to the grid adjustment in plotmes (util)
1.0.7: getMinMax can be called with a selection name
1.0.8: save function
1.0.9: SimulationError exception catching + save(identical to MMI); requires numpy 1.8.1
1.1.0: same as 1.0.9 but requires only numpy 1.7.1
1.1.1: minor change to codewinfile=winstr
1.1.2: added 'execute' for multiple commands as strings (\n managed as a separator)
1.1.3: (141104) disable useoffset for Y axes in 'util.plotmes'
1.1.4: (141118) handling Picwin32.dll provided by GFI after 18-11-2014 (best 03-12-2014)
1.1.5: (141205) handling ts < ms in tsvalbymts
1.1.6: (150127) nodeXYZ added + bugfix in attrs documentation
1.1.7: (150309) minor grammatical changes
1.2.0: (150507) change in folder search order (ws7 priority) + language - OK with Picwin32 151203
1.2.1: (150527) Picalor enabled as ganessa.th + density and SHL management; (150603) added 'meanattr'; (150610) added 'addSHLtype'
1.2.2: (150709) bug fix calls select* from Selected
1.2.3: (150812) bug fix: return value of browseWQ; getall
1.2.4: (150910) Constants added (WQ, Inverse Pb) + DemandCodes
1.2.5: (150922) utils: tuning of plotmes subtitle fontsize for large titles + Constants (MOD, NOD ...) + 'areas' function
1.2.6: (151128) added tsdemand and tsdemandlen, tsdevice and tsdevicelen; added tables (material, area etc.) access; utils: added list2file
1.3.0: (151202) added support for Compatibility with Picwin32 12/2014, 12/2015 and Ganessa; (151206) addl Constants (BRA, DYN, RSV); (151218) reviewed Compatibility with Picwin32 (2015+ -> Piccolo6), (2014 -> Piccolo5)
1.3.1: (160108) header, footer and suffix optional args for utils.list2file; (160113) added memory allocation error exception (inverse module)
1.3.2: (160118) added retrieval of problematic devices; (160126) added 'H' TANK attribute in util.plotmes(x)
1.3.3: (160226) added getindex, tankattrs, linkattr and linkattrs
1.3.4: (160301) added Constants for inverse pb; (160309) added inverse simulation summary; (160318) added added nxxxxattr and nxxxxatrs function for getting attributes by index; (160325) added file quote as needed in save function; (160329) corrected doc (selectlen/select); (160405) corrected doc, added linkXYZV; (160408) utils: strloc, strf3loc
1.3.5: (160410) added init(folder)
1.3.6: (160511) added 'symmetric_node' (Ganessa_TH); (160531) reviewed Compatibility with dll versions since 2014.
1.3.7: (160622) added OpenFileMMI Classes: SelectModel, SelectFile, ExecStatus; (160706) added 'dist2link'; added 'util.dist_to_poly' as pure python backup; OpenFileMMI uses simulation interface from caller, or NONE; changed all Classes to new style; added 'len' method to 'Selected' and 'Elements'; added 'Graph'
1.4.0: (160715) setup changed to build whl from source files; (160719) minor bug fix in util.plotmes - reuse same fig in non interactive mode
1.4.1: (160820) OpenFileMMI SelectFile with null extension; load error handling
1.4.2: (160830) added AUTO and QUAL storestep Constants; minor fix in gencmd; added include_depth optional attribute to 'linkXYZV'; (160915) added version_2016b in the Picwin32 lookup Table; (160919) added SelectFolder in OpenFileMMI; (160922) added setlinkattr as a synonym of setbranchattr; (160927) intermediate API for Piccolo6 2016 B (dec-2016)
1.5.0: (161010) added 'getkeyword'; (161019) minor change in util.plotmes: 160719 patch reviewed for better output; (161124) added 'stat_quantiles', 'stat_duration', and 'Dynamic_Stats'
1.5.1 (161212) bug fix on ts* functions without result file; added 'retry' optional argument to full_solveH
1.5.2 (170105) added folder= option in util.list2file (170110) build with numpy 1.11.0 - compatible with
1.7.0 (170119) build with BIND(C) instead of DEC$ATTRIBUTE C, REFERENCE; required with ganessa_SIM > 170117 (renamed API functions); (170125) added fixed_interval to tsdevice, now return float values
1.7.1 (170221) minor changes in util.IniFile (default encoding utf-8); switch to unicode_literals in sim&th, util and prot; (170223) added compiled util.dist, util.dist_p_seg, util.dist_to_poly
1.7.2 (170228) added OpenFileMMI.setlanguage function (FR/US or UK); (170304) fix getMinMax/getallminmax break in 1.7.0
1.7.3 (170313) added WQ, MOD and LNK Constants; added DICT.END; added modulekeyword and attrkeyword; (170331) added shearstr; match Piccolo 2017 --> NO !
1.7.4 (170407) added silent option to init; (170424) added default '@safege.com' domain to util.envoi_msg
1.7.5 (170426) improved util.plotmes(x) for horizon > 24h; (170512) added module 'multithread'; (170515) fix parent.inidir error in OpenFileMMI; added solveH
1.7.6 (170613) added Constants (STATIC, QUA.VISUSTEP) and util.group; minor bug fix in Selected, getMinMax and Dynamic_Stats; (170618) added title to OpenFileMMI.SelectFile and SelectFolder; added util.pageplot; (170620) replaced litteral symbols with attrkeyword(); (170627) match Piccolo 2017 (apr 2017);
1.7.7 (170705) added cwfold; (170707) optional arg for sim&th.close(arg) and prot.close(arg); added C1 in util.plotmes for chlorine plots;
1.7.8pr1 (170808) doc update; upload to pypi
1.7.8 (170817) replaced IniFile with json/xml version
1.7.9pr1 (170824) prepared for Piccolo 2017b; (170830) added getunitcoef
1.8.0 (170907) sim.py split into core, core_sim, core_th; changed/fixed path lookup; (170918) added resfile, raw_getcmdw, raw_stat_duration, raw_stat_quantiles
1.8.1 (171004) added util.update_package
1.8.2 (171016) added util.str2uni (tries utf8 the cp1252 - reverse from unistr); (171018) minor bug fix for util.update_package; (171103) added sort.HeapSort class and Graph.dtree
1.8.3 (171109) added error msg when OpenFileMMI is imported before sim or th; (171110) fix _pyganutl import broken in 1.8.0 (util.dist, util.dist_to_poly); (171114) added multithread.MultiProc class
1.8.4 (171120) bug fix / changed multithread.MultiProc.run return values as 3 lists
1.8.5 (171120) added util.plot_close to avoid Fatal Python error at exit; (171128) added linkbbox and util.gbool
1.8.6 (171201) added progress keyword to parallel.MultiProc; full_version; added util.send_report
1.8.7 (171208) fix update_package not succeeding in update 'ganessa'
1.8.8 (171212) improved update_package proxy configuration using .json files; added Picwin32.dll lookup into PICCOLO_DIR environment variable and '_ck' optional folder suffix
1.8.9 (171220) updated full_version; added UPN lookup in send_report; (180126) added importEpanet and exportEpanet
1.9.0 (180227) added con2uni for converting console output to unicode (cp850) (180305) fixes related to 2to3: _getdll: environ; util: winstr and utf, IniFile encoding, cmp_version, added version_as_tuple (180328) send_report timeout to 2 seconds, added util.is_text; 2 and 3 Compatibility changes for unistr, str2uni, utf2uni, ascii.
1.9.1 (180418) added a reduce function to parallel.MultiProc; fix seq run (180502) update_package looks for package in current folder
1.9.2 (180514) fix python3 issue in parallel submodule; minor OpenFileMMI fixes (180518) fix update_package Compatibility with parallel
1.9.3 (180525) fix epanet.getlinknodes (180530) added util.ws

5. ganessa.sim&th/Classes [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Classes available to ganessa.sim and ganessa.th

5.1. Classes/Graph, extrnodes,
adjlinks, adjnodes,
propagate, dtree [ Objects ]

[ Top ] [ Classes ] [ Objects ]

PURPOSE

Builds a simple Graph from the current model topology.

SYNTAX

Graph = Graph()

METHODS

from_n, to_n = Graph.extrnodes(alink): returns the from and to Nodes of alink
linkset = Graph.adjlinks(anode): returns Links adjacent to anode as a set
nodeset = Graph.adjnodes(anode): returns Nodes adjacent to anode as a set
plist = Graph.oriented_links(anode): returns a list of (LINK, index) tuples
slinks, snodes = Graph.propagate(anode [, maxlen= -1]): returns the sets of Links and Nodes connected to 'anode' by a path of max length 'maxlen'
dtree, slinks = Graph.dtree(anode [, maxlen= -1]): returns a tree as an ordered DICT

ARGUMENTS

alink, anode: LINK, NODE ID

RESULT

The Graph is built from the current model Links and Nodes:

set linkset: set of adjacent Links ID
set nodeset: set of adjacent Nodes ID
plist: list of tuples (ID alink, int idx) where idx is the index of the other NODE in Graph.edges[alink] (Graph.edges[alink][1-idx] == anode).
sets slinks, snodes: sets of Links and Nodes ID.
OrderedDict dtree: ordered DICT where key are NODE IDs, values are a LINK ID and a depth integer value. The LINK allows to connect the NODE.

REMARK

first key, value returned by dtree is the root NODE, and ('', 0)

HISTORY

new in 1.3.7 (160706)
reviewed 1.7.6 (170620): use attrkeyword() for IN and FN
reviewed 1.8.2 (171103): added Graph.dtree
reviewed 1.8.5 (171128): updated dtree, added Graph.adjnodes

6. ganessa.sim&th/Compatibility [ Introduction ]

[ Top ] [ Introduction ]

PURPOSE

The installation of pyganessa is compatible with several versions of Picwin32.dll (regular Piccolo / Picalor). Missing functions in older versions should NOT be called.

HISTORY

2014 -> 141203 Piccolo5 -- release 2014
(2015a -> 151217 Piccolo6 & Picalor6 -- release 2015 (Unstable)) - discarded
2015 -> 160121 Piccolo6 -- release 2015 sp1
2016 -> 160419 Piccolo6 & Picalor6 -- release 2016
2016a -> 160930 Piccolo6 release 2016b (incomplete; compatible with 1.4.2)
2016b -> 161216 Piccolo6 & Picalor6 -- release 2016b (1.5.0 - 1.5.2)
2017 -> 170627 Piccolo6 & Picalor6 -- release 2017 (1.7.7 - 1.7.8)
2017b -> 1709xx Piccolo6 & Picalor6 -- release 2017b (1.8.0 - )

REMARK

pyganessa is compatible with matching or newer versions of Ganessa_SIM/Ganessa_TH.dll only; except a Compatibility break on 170117.

7. ganessa.sim&th/Constants [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Several categories of Constants are available:

Constants defining a type of element: see BRANCH or LINK, NODE, RESERVOIR or TANK
Constants defining a command module: M.COM or M.ROOT, M.GEN, M.SIM etc.
Constants defining a command within a module: M.SIM.EXEC
keywords

7.1. Constants/BRANCH, LINK,
NODE, NOEUD,
TANK, RESERVOIR,
RSV [ Constants ]

[ Top ] [ Constants ] [ Constants ]

DESCRIPTION

Those Constants allow to select one of the three types of model Elements:

LINK or BRANCH: Branches Elements such as pipes, pumps, valves
NODE or NOEUD
TANK or RESERVOIR or or RSV

REMARK

M.LNK, M.NOD and M.RSV are object Constants for calling BRANCH, NODE and RESERVOIR modules

7.2. Constants/DICT [ Constants ]

[ Top ] [ Constants ] [ Constants ]

DESCRIPTION

The DICT class provide a dictionnary tree for keywords

SYNTAX

DICT.SYMBOLIC_NAME

CONTENT

FULLPER: extended simulation (ENCHAINE in French)
EXPORT
INSTANT

7.3. Constants/M, NONE [ Constants ]

[ Top ] [ Constants ] [ Constants ]

DESCRIPTION

The M class provide a dictionnary tree for modules. It provides a hierarchical naming of the commands by modules, for building language-independant commands using gencmd, gencmdw, _gencmdw functions.

SYNTAX

One of the following:

M.MODULE_SYMBOLIC_NAME
M.MODULE_SYMBOLIC_NAME.COMMAND__SYMBOLIC_NAME or
M.MODULE_SYMBOLIC_NAME..NONE or M.NONE or M.VOID

CONTENT

The available MODULE_SYMBOLIC_NAME are:

ROOT: modules names: BRA, NOD, RSV, DYN, MOD, SIM, QUA, MES, LAB, FIR, INV, OPT. They can be used in three forms, as first argument for the functions above:

M.ROOT.SIM or M.SIM.ROOT: equals the index of the module name
M.SIM: can be used in gencmd and gencmdw only as first argument

GEN: general purpose commands:

LOAD: load a binary file
OPEN and close: open and close an output file
quit: the quit command
READ: read a command language or data file
example: gencmd(M.GEN, M.GEN.OPEN, DICT.EXPORT, 'filename.txt')
EXPORT, save: export or save to a (previously opened) file
IMPORT: import attributes for a type of element from a file
FIND: command for retrieving a given period or instant
MESSAGE: writes a message to the console
DEFPARAM, DEFVAR: define a positional parameter (%1 ... %9) or variable
UNIT: redefine units name and coef
EOF: the end-of-file command

LNK: LINK commands and submodules, including LINK types (.PIPE .PUMP .NRV .PRV .PSV .FCV .TCV etc.)

NOD: NODE commands and submodules:

CONS: demand acquisition submodule
COEF, AREA: demand coefficient by demand type and area
TOPO: topograpy submodule

RSV: RESERVOIR command and submodules:

CHAR: characteristics
LEVEL: initial level acquisition submodule

MES: measurement commands:

SMOOTH: allow to define the smoothing interval

SIM: simulation commands:

FILE: define a result file name
EXEC: runs the simulation

QUA: Water quality module commands

REMARK

The above codes are not exhaustive. Please refer to the script.

8. ganessa.sim&th/Functions [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Functions available to ganessa.sim and ganessa.th

8.1. Functions/addSHLtype, addSHL,
updateSHL, delSHL [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

addSHLtype: Add / modify a single head losses (SHL) from the SHL Table
addSHL, updateSHL, delSHL: Add / modify / delete single head losses (SHL) objects for a given pipe

SYNTAX

istat = addSHLtype(shltype, values [, comment])
istat = addSHL(id, shltype, nb)
istat = updateSHL(id, shltype, nb)
istat = delSHL(id [, shltype])

ARGUMENTS

string shltype: type of shl to be added/modified
float values: direct and reverse SHL coefficients
string comment: long name of the SHL type
string id: id of pipe
int nb: number of SHL of type shltype to be added / updated with

RESULT

int istat: error status (0 if OK) COMMENTS If shltype is not given or is '' for delSHL then all SHL are removed from pipe.

REMARK

these functions require version 2015/12 or higher of Piccolo/Ganessa dll

8.2. Functions/areas [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

return areas associated with Nodes/Links

SYNTAX

area = areas(typelt, attr)

ARGUMENTS

int typelt: type of object (NODE or LINK)
str attr (optional): area attribute to be returned (ZN or ZP). Default to 'ZN'

RESULT

counter area: dictionary of NODE/LINK counts by area

HISTORY

From version 1.9.0 (05/04/2018) area are returned as unicode strings.

8.3. Functions/cmd, addcmdw,
execute, cmdfile [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

istat = cmd(scmd)
istat = cmdfile(fname [, args])
istat = addcmdw(scmd)
istat = execute(scmd1 [ ..., scmdn][, dbg= True])

ARGUMENTS

string scmd: command line to be executed
string fname: data/command file name to be read/executed
string args: optional argument(s) to the command file, as one single string
string scmd1: command line(s) to be executed ('\n' is handled as a command delimiter)
string scmdn: optional command lines(s) to be executed (same as scmd1)
boolean dbg: optional, makes commands to be echoed in the log file.

RESULT

int istat: error status (0 if OK)

REMARKS

cmd executes the given command
cmdfile reads/executes the commands from the file.
addcmdw pushes the command onto the command stack.
execute pushes the given commands on the stack and executes them

If an error occurs while reading a file or nested files, the execution stops. If the useException mode is set, the error will raise a GanessaError

8.4. Functions/commit [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Executes all the commands available on the stack (first in, first executed)

SYNTAX

istat = commit()

RESULT

int istat: error status (0 if OK)

REMARK

If an error occurs, the remaining part of the stack is cleared

8.5. Functions/cwfold [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

ret = cwfold(folder)

ARGUMENT

str folder: folder name where journal (piccolo.jnl) and work files will be created

RESULT

bool ret: True if folder exists; False otherwise

HISTORY

introduced in 1.7.7 (170705)

8.6. Functions/dist2link [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the distance and curvilinear abcissae of a point from the given LINK

SYNTAX

d, s1, s2 = dist2link(id, x, y)

ARGUMENTS

string id: id of LINK element
double x, y: coordinates of the point

RESULT

double d: distance of the point to the LINK polyline
double s1, s2: curvilinear distance of the projection from each extremity

HISTORY

introduced in 1.3.7 (160706)

REMARKS

dist2link requires version 2016b or higher of Piccolo/Ganessa dll; if not a pure python calculation is made using linkXYZV
the polyline length is s1 + s2; s1= 0 or s2= 0 when the point projection is outside the polyline
if the id does not exists the return value is (-1, -1, -1)

8.7. Functions/dll_version, full_version [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

yymmdd = dll_version()
text = full_version()

RESULT

int yymmdd = dll version()
str text = full_version()

HISTORY

dll_version introduced in 1.8.0 (170907)
full_version introduced in 1.8.6 (171201)

8.8. Functions/extrnodes [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the from and to NODE (indexes) form BRANCH index

SYNTAX

i_from, i_to = extrnodes(i_branch)

ARGUMENTS

int i_branch: index of the BRANCH

RESULT

int i_from: index of from NODE
int i_to: index of to NODE

REMARKS

Internal indexes start with 1
Internal index of an element may change after a simulation or a modification of the model.

8.9. Functions/gencmd, gencmdw,
_gencmdw [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Those fuctions allow to generate a language independant command line based upon the keywords id of a module and its commands (see M).

SYNTAX

istat = gencmd (module, icmd, [word, scmd, extmode])
istat = gencmdw(module, icmd, [word, scmd, extmode])
istat = _gencmdw(module, icmd, [word, scmd, extmode])

ARGUMENTS

module: constant id for the module
icmd: constant id for the command in the module (or NONE)
word: constant id for a keyword (or NONE) (optional)
scmd: additional string (optional)
extmode: if set to 1, the command is appended to the previous one (optional)
string scmd: command line to be executed

RESULT

int istat: error status (0 if OK)

REMARKS

gencmd builds and executes the given command
gencmdw and _gencmdw build the command and push it onto the command stack
gencmd and gencmdw allow a more flexible entry of the first 2 arguments
If the useException mode is set, an error will raise a GanessaError
raw_gencmdw is an exported version of _gencmdw

EXAMPLES

The following are equivalent:

istat = _gencmdw(M.SIM.ROOT, M.SIM.EXEC, DICT.FULLPER)
istat = gencmdw(M.SIM, "EXEC", DICT.FULLPER)

The following are equivalent:

istat = _gencmdw(M.SIM.ROOT, M.SIM.EXEC, scmd="15:30")
istat = gencmdw(M.SIM, "EXEC", scmd="15:30")

HISTORY

1.8.0 (170908): added raw_gencmdw

8.10. Functions/getall [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

getall returns the value for all objects of the given type for all objects of the given type

SYNTAX

vect = getall(typelt, attr)

ARGUMENTS

int typelt: type of element (LINK, NODE, TANK)
string attr: attribute (result) for which value is requested

RESULT

float[] vect: vector of values

REMARKS

getall(typelt, attr): when typelt =1 (Links), attr can be either a regular attribute ('Q', 'V', 'D', etc.) or a NODE-based attribute such as 'P:M' for mean pressure, 'P:G' for geometric mean, 'P:N' for min and 'p:X' for max.

8.11. Functions/getcodescount, nextcode [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

getcodescount: returns count of used demand codes
nextcode: returns the list of used codes with NODE count

SYNTAX

ncodes = getcodescount(used_only)
code, demand, count, nbchar = nextcode()

ARGUMENTS

bool used_only: if True, only codes associated with at least one NODE will be returned

RESULT

int ncodes: number of codes to be returned
str code: demand codes
float demand: total nominal demand for the code
int count: NODE count
int nbchar: nb of chars in the demand code string

REMARKS

these functions require version 2016 or higher of Piccolo/Ganessa dll
If the GanSim Dll is too old those function will not return data
See also the Demands(id) iterator

HISTORY

From version 1.9.0 (05/04/2018) codes are returned as unicode strings.

8.12. Functions/getdemandbycode, getcodedemandinit,
nextcodedemand [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

getdemandbycode: returns demand for a given NODE and consumer code by id
getcodedemandinit: initialises and returns the number of pairs

SYNTAX

demand, istat = getdemandbycode(id, code)
nbpairs = getcodedemandinit(id)
code, demand, codelen = nextcodedemand()

ARGUMENTS

string id: id of NODE
string code: code for which demand value is requested
int nbpairs: number of demand, csm pairs for the NODE

RESULT

float demand: value of the demand (0 if not available)
int istat: return code (0= 0K -1= unknown code 1= unknown NODE 3= dll too old)
int nbpairs: number of code, demand pairs for the NODE
string code: demand code
int codelen: length of code string

REMARKS

these functions require version 2016 or higher of the Piccolo/Ganessa dll
If the GanSim Dll is too old those function will not return data
See also the Demands(id) iterator

HISTORY

From version 1.9.0 (05/04/2018) codes are returned as unicode strings.

8.13. Functions/getid [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the id of an element by type and index

SYNTAX

id = getid(typelt, numelt)

ARGUMENTS

int typelt: type of element
int numelt: index of element

RESULT

unicode string id: id of the element

REMARKS

Internal index starts with 1
Internal index of an element may change after a simulation or a modification of the model.

HISTORY

From version 1.9.0 (05/04/2018) ids are returned as unicode strings.

8.14. Functions/getindex [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

num = getindex(typelt, id)

ARGUMENT

int typelt: type of element string id: ID of element

RESULT

int num: index of element ID (starting at pos 1)

HISTORY

new in 1.3.3

8.15. Functions/getkeyword, modulekeyword,
attrkeyword [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

get keyword or command name by index - for building command language independant functions

SYNTAX

sret = getkeyword(code)
sret = modulekeyword(module, submodule)
sret = attrkeyword(attr)

ARGUMENTS

code: int code of the keyword (>0) or global command (<0)
module: int code of the module (<0 for the submodule alone)
submodule: int code of the module (0 for the module alone)
attr: int code of the attribute

RESULT

str sret: trimmed value of the keyword or global command or module submodule

         (null string if the code or module/submodule is not recognised)

HISTORY

getkeyword introduced in 1.4.2 (161010)
modulekeyword and attrkeyword intoduced in 1.7.3 (170313)
From version 1.9.0 (05/04/2018) results are returned as unicode strings.

8.16. Functions/getvar, getunitname,
getunitcoef [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the value of a Piccolo expression or variable

SYNTAX

str_val = getvar(expression)
str_val = getunitname(attr)
coef = getunitcoef(attr)

ARGUMENTS

string expression: the expression or variable to be returned
string attr: attribute

RESULT

string str_val: a string containing the expected value
float coef: a float giving the unit coefficient / internal units

REMARKS

Unit coefficient of a given attribute can also be returned with the adequate getvar('unite.'+attr).
The unit coefficient is the number of internal units per user units: 1 (user unit) = coef (internal unit).

Internal units are SI units excepted:

diameter and roughness: mm
pressure: mwc
concentrations: mg/l (or ppm)
consumed mass (D1): g

EXAMPLE

If the user flow unit is 'l/s', since internal flow unit is 'm3/s', getunitcoef('Q') returns 0.001

HISTORY

From version 1.9.0 (05/04/2018) info returned as unicode strings.

8.17. Functions/importEpanet, exportEpanet [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

istat = importEpanet(fname)
istat = exportEpanet(fname)

ARGUMENTS

string fname: file name to import from / export to (should be an .inp)

RESULT

int istat: error status (0 if OK)

REMARK

At import, .inp file is first converted to a .inp_cvt.dat Piccolo file, then this file is read. Syntax error if any will refer to the converted .dat file.

8.18. Functions/init [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

init([folder])

ARGUMENT

str folder: optional folder name where journal and work files will be created

DESCRIPTION

Initialises the ganessa simulation/command language engine.

REMARKS

Starting with version 1.3.5, a session should be started by calling init() or init(folder). however for Compatibility with previous releases where init was called at import time, init is automatically called at 1st call of cmd, cmdfile, execute, load, loadbin
A session should be terminated by calling quit() or typing <Ctrl>+Z

HISTORY

introduced in 1.3.5

8.19. Functions/linkattr, nodeattr,
tankattr, linkattrs,
nodeattrs, tankattrs,
attr, attrs,
meanattr [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

linkattr, nodeattr, rsvattr, attr: return numerical attributes of a given element by id
linkattrs, nodeattrs, attrs: return text attributes of a given element by id
meanattr: return mean attribute of from and to Nodes given by BRANCH id

SYNTAX

val = linkattr(id, attr)
val = nodeattr(id, attr)
val = tankattr(id, attr)
txt = linkattrs(id, attr)
txt = nodeattrs(id, attr)
txt = tankattrs(id, attr)
val = attr[typelt](id, attr)
btxt, sz = attrs(typelt, id, attr)
val = meanattr(id, attr)

ARGUMENTS

string id: id of element
string attr: attribute (data or result) for which value is requested
int typelt: type of element

RESULT

float val: value of the numerical attribute (0. if not available)
string txt: value of the text attribute (empty string '' if undefined or not available)
byte btxt: value of the text attribute, as a byte (python3) or str(python2)
int sz: length of the returned string

REMARKS

Numerical attributes are returned converted in the actual unit system.
RESERVOIR text attributes are identical to the underlying NODE id
meanattr requires version 2016 or higher of Piccolo/Ganessa dll
branchattr, rsvattr and branchattrs are synonyms for linkattr, tankattr and linkattrs

HISTORY

From version 1.9.0 (05/04/2018) ids and attributes are returned as unicode strings.

8.20. Functions/linkbbox [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the LINK bounding box

SYNTAX

xmin, xmax, ymin, ymax, num = linkbbox(id)

ARGUMENTS

string id: id of element

RESULT

int num: LINK internal number (0 if not found)
double xmin, xmax, ymin, ymax: bounding box

HISTORY

Created in 1.8.5 (171128)

8.21. Functions/linkXYZV, branchXYZV [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the XYZ polyline representing a LINK, and eventually an additional NODE attribute

SYNTAX

vec_x, vec_y, vec_z, vec_v, len = linkXYZV(id, [attr], [include_depth])

ARGUMENTS

string id: id of element
string attr: optional attribute for which value is requested
bool include_depth: optional attribute, defaults to False

RESULT

int len: number of points for the polyline
double[] vec_x, vec_y: vector of coordinates
float[] vec_z: vector of interpolated elevations (minus depth if include_depth= True)
float[] vec_v: vector of interpolated attribute

HISTORY

optional argument include_depth introduced in 1.4.2 (160908)

REMARKS

Z and V are interpolated from initial and final Nodes
if attribute is missing or not recognised vec_v is null.
if the LINK has no vertice, len=2 and the function returns values from ending Nodes
if the id does not exists the return value is (NONE, NONE, NONE, NONE, 0)
branchXYZV is a synonym of linkXYZV.

8.22. Functions/loadbin [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Clears (removes) all model objects and loads a binary file

SYNTAX

istat = loadbin(fname)

ARGUMENT

string fname: binary data/result file name to be loaded

RESULT

int istat: error status (0 if OK)

REMARKS

The current model is discarded before the new one is loaded.
If the file content is not a Piccolo binary file an error occurs.
Binary result files also contain all data describing the model.

8.23. Functions/loadres [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Loads the default binary result file.

SYNTAX

istat = loadres()

RESULT

int istat: error status (0 if OK)

REMARK

The current model is discarded before the data corresponding to the last simulation making use of the default result file is loaded.

8.24. Functions/nbobjects [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the number of model Elements in the given type

SYNTAX

nb = nbobjects(typelt)

ARGUMENT

int typelt: type of element (LINK, NODE, TANK)

RESULT

int nb: number of element in that type

8.25. Functions/nlinkattr, nnodeattr,
ntankattr, nlinkattrs,
nnodeattrs, ntankattrs,
nattr, nattrs [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

nlinkattr, nnodeattr, nrsvattr, nattr: return numerical attributes of a given element by index
nlinkattrs, nnodeattrs, nattrs: return text attributes of a given element by index

SYNTAX

val = nlinkattr(num, attr)
val = nnodeattr(num, attr)
val = ntankattr(num, attr)
txt = nlinkattrs(num, attr)
txt = nnodeattrs(num, attr)
txt = ntankattrs(num, attr)
val = nattr[typelt](num, attr)
btxt, sz = nattrs(typelt, num, attr)

ARGUMENTS

string num: index of element (stating at 1)
string id_or_num: id or index of element
string attr: attribute (data or result) for which value is requested
int typelt: type of element

RESULT

float val: value of the numerical attribute (0. if not available)
string txt: value of the text attribute (empty string '' if undefined or not available)
int sz: length of the returned string
byte btxt: value of the text attribute, as a byte (python3) or str(python2)

REMARKS

Numerical attributes are returned converted in the actual unit system.
TANK text attributes are identical to the underlying NODE id

HISTORY

From version 1.9.0 (05/04/2018) ids and attributes are returned as unicode strings.

8.26. Functions/nodeXYZ [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the XYZ coordinates and depth of a NODE

SYNTAX

x, y, z, dz = nodeXYZ(id)

ARGUMENTS

string id: id of element

RESULT

double x, y: coordinates
float z, dz: elevation and depth

REMARKS

nodeXYZ requires version 2016 or higher of Piccolo/Ganessa dll
if the id does not exists the return value is (NONE, NONE, NONE, NONE)
In most cases dz is 0.0

8.27. Functions/quit, close [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

ret = quit([True])

ARGUMENT

optional bool verbose: if set to True, a message is printed. Defaults to False.

RESULT

text ret: text string telling that he module has been unloaded. Terminates the ganessa session and unloads the module ganessa.sim&th

REMARKS

quit() is automatically called when quitting with <Ctrl>+Z
close() is a synonym for quit()
A session should be terminated by calling quit() or typing <Ctrl>+Z
sys.exit() automatically trigers quit()

8.28. Functions/reset [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Clears (removes) all model objects

SYNTAX

istat = reset()

RESULT

int istat: error status (0 if OK)

8.29. Functions/resfile [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the name of the default binary result file.

SYNTAX

name = resfile()

RESULT

str name: file name or '' if undefined

HISTORY

Introduced in version 1.8.0 (170919)

8.30. Functions/save, savemodel [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

istat = save(fname [, version])
istat = savemodel(fname [, version])

ARGUMENTS

string fname: file name to save to
string version: optional version string "x.yz" for writing compatible file format, for text file only.

RESULT

int istat: error status (0 if OK)

REMARKS

'save' uses the same procedure as Piccolo MMI.
'savemodel' is pure python and produces the same hydraulic content; exotic options and cost data are not saved.
If filename ends with '.bin' then data is saved as binary. Otherwise data is saved as text (.dat mode) file.
If the useException mode is set, any error will raise GanessaError exception.

8.31. Functions/selectlen, select [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

selectlen returns the number and type of model Elements in the given selection
select: returns the index vector, number and type of Elements in the selection

SYNTAX

nb, typelt = selectlen(sname)
vect_idx, nb, typelt = select(sname)

ARGUMENT

string sname: name of selection

RESULT

int nb: number of element in that selection
int typelt: type of element of that selection
int vect_idx[]: index vector of Elements in the selection

8.32. Functions/setbatchmode [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

oldmode = setbatchmode(mode)

ARGUMENT

int mode: batch mode to activate

RESULT

int oldmode: batch mode that was in effect

REMARK

Defaults to 1 (True)

8.33. Functions/setlang [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

oldlang = setlang(new_lang)

ARGUMENT

str new_lang: one of 'English', 'French', 'Spanish'

RESULT

str old_lang: previous language

DESCRIPTION

Modifiy the current command language to new_lang (console version and macros only). If the language name is misspelled, it will be ignored withour raising an error.

HISTORY

introduced in 1.8.0 (170912)

8.34. Functions/setlinkattr, setbranchattr [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

istat = setlinkattr(id, attr, val)
istat = setbranchattr(id, attr, val)

ARGUMENTS

string id: id of element
string attr: attribute (data or result) to be set to val
float val: new value for attr

RESULT

int istat: error status:

0 if OK
1 if the attribute is not defined for the type of LINK
-1 if the attribute is not recognised
-2 if the LINK does not exist

REMARKS

setbranchattr requires version 2015/12 or higher of Piccolo/Ganessa dll
setlinkattr is a synonym that has been introduced as 22/09/2016

8.35. Functions/shearstr [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the shear stress associated with a velocity for the given pipe

SYNTAX

val, grad = shearstr(id, v)

ARGUMENTS

string id: id of element
float v: velocity for which value is requested

RESULT

float val: value of the shear stress
float grad: value of ds/dv

REMARKS

val is not defined if id is not a pipe
requires Piccolo 2017

HISTORY

31.03.2017: function created (1.7.3)

8.36. Functions/useExceptions, GanessaError,
SimulationError [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

oldstat = useExceptions([status])
try: ... except GanessaError:
try: ... except SimulationError [as exc]:

ARGUMENTS

bool status: if True, errors will raise exceptions

RESULT

bool oldstat: previous error handling mode
exception exc: excetion object. The attribute exc.reason will provide additional information on the origin of error

DESCRIPTION

SimulationError is a derived class of GanessaError. The simulation error subtypes are the following:

SIMERR.ISOL: Isolated Nodes
SIMERR.SLOW_CV: Slow convergence (convergence not obtained within max iteration count)
SIMERR.Unstable: Unstability (flip between 2 or more equilibrium points)
SIMERR.FCTAPP: Equipment(s) or storage(s) do not operate properly; they can be retrieved with the Unstable() iterator
SIMERR.DIVERGE: Divergence (convergence error increase)
SIMERR.STRUCT: Structural inconsistency
SIMERR.MEMALLOC: Memory allocation error (WQ or inverse problem)

REMARK

Defaults to False: errors do not raise 'GanessaError' exceptions. If set to True, errors raise exceptions with a string name giving the error message and a int reason giving the type of exception.

9. ganessa.sim&th/Iterators [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Iterators available to ganessa.sim and ganessa.th

9.1. Iterators/Branches, Links [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

SYNTAX

for id in Branches():
for id in Links():

RESULT

string id: returns each BRANCH id in turn

REMARK

Branches and Links are synonyms

HISTORY

From version 1.9.0 (05/04/2018) ids are returned as unicode strings.

9.2. Iterators/DemandCodes [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

SYNTAX

for code, demand, nodecount in DemandCodes():

RESULT

Returns each demand code and NODE count in turn:

string code: demand code
float demand: total demand value for the code
int count: NODE count associated with the code

REMARK

DemandCodes requires version 2016 or higher of Piccolo/Ganessa dll

HISTORY

Added 11/09/2015

9.3. Iterators/Demands [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

SYNTAX

for code, csm in Demands(node_id):

ARGUMENT

string node_id: id of NODE

RESULT

Returns each demand code and nominal value for the NODE in turn:

string code: demand code
float csm: demand value for this code

REMARK

requires version 2016 or higher of Piccolo/Ganessa dll

HISTORY

From version 1.9.0 (05/04/2018) codes are returned as unicode strings.

9.4. Iterators/Elements [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

SYNTAX

for id in Elements(typelt):

ARGUMENT

int typelt: type element Constants LINK, NODE, TANK

RESULT

string id: id of each element of the given type in turn

HISTORY

From version 1.9.0 (05/04/2018) ids are returned as unicode strings.

9.5. Iterators/Nodes [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

SYNTAX

for id in Nodes():

RESULT

Returns each NODE id in turn

HISTORY

From version 1.9.0 (05/04/2018) ids are returned as unicode strings.

9.6. Iterators/Selected [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

SYNTAX

for id, typelt in Selected(sname):

ARGUMENT

string sname: name of a selection

RESULT

Returns the id and type of each element in the selection in turn:

string id: id of the next element in the selection
int type: element type (the same for all ids)

9.7. Iterators/Table [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

SYNTAX

for item, objcount in Table(Table, typelt):

ARGUMENTS

string Table: requested Table (2 char symbol or Table name)
int typelt: type of element (LINK or NODE), if Table is ZN or ZP. Defaults to LINK.

RESULT

Returns each Table entry and associated object count in turn:

string item: Table entry
int objcount: NODE count associated with the code

REMARK

Table requires version 2015/12 or higher of Piccolo/Ganessa dll

HISTORY

From version 1.9.0 (05/04/2018) items are returned as unicode strings.

9.8. Iterators/Tanks, Reservoirs [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

SYNTAX

for id in Tanks():
for id in Reservoirs():

RESULT

string id: returns each RESERVOIR id in turn

HISTORY

From version 1.9.0 (05/04/2018) ids are returned as unicode strings.

9.9. Iterators/Unstable [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

PURPOSE

Provide access to the list of Elements which status cannot be determined thus causing a simulation not converge.

SYNTAX

for item, typelt in Unstable():

ARGUMENTS

NONE

RESULT

Returns each Unstable element in turn:

string item: element ID
int typelt: element type

REMARK

Unstable requires version 2016 (160118) or higher of Piccolo/Ganessa dll

HISTORY

new in 1.3.2
From version 1.9.0 (05/04/2018) items are returned as unicode strings.

10. ganessa.sim/sFunctions [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Functions available to ganessa.sim ONLY.

10.1. sFunctions/browseH, browseWQ [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

Retrieves and interpolate results from a given time step or instant:

browseH retrieves hydraulic results
browseWQ retrieves hydraulic and water quality results

SYNTAX

istat = browseH(time_step)
istat = browseH(instant)

ARGUMENTS

int time_step: time step to load
string instant: instant to load, in the form hh:mm:ss

RESULT

int istat: error status (0 if OK)

REMARKS

For hydraulic results, two set of results may be available at a given instant:

at boudary of time steps, except beginning and end of the simulation, results ending the previous time step and results starting the next time step.
at internal time steps when a state transition occured (pump start/stop etc.).

In such a situation the results are those from the end of the previous interval.

10.2. sFunctions/defcalind, getcalind [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

Compute and return calibration indicators

SYNTAX

defcalind(br_threshold, no_threshold, rsv_threshold)
val, ival = getcalind(typelt, numelt)

ARGUMENTS

br_*** : thresholds for computing indicators
int typelt: type of element
string id: id of element

RESULT

val: percentage of values below threshold ival: indicator rank, from 1 (best) to 4 (worse) (-1 if not defined)

REMARK

defcalind actually compute all indicators; getcalind returns them.

10.3. sFunctions/full_solveH [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

Runs the full simulation and loads the result file for browsing results

SYNTAX

istat = full_solveH([resultfile] [, silent] [, iverb] [, retry])

ARGUMENT

string resultfile: if provided, the results will be written in the file instead of the default 'result.bin'. If the file exists it will be superseded. If not it will be created.
bool silent: if set to True, simulation runs without any output. Optional - if False or not set, leaves 'iverb' unchanged.
integer iverb: if provided, controls the amount of output during simulation (SIM IVERB parameter). The defaults is -1.
bool retry: if set to True, the simulation is run again if it fails because of isolated Nodes. Optional - defaults to False

RESULT

int istat: error status (0 if OK)

REMARKS

Unless explicitely disabled, results are saved to a binary file, which defaults to the file 'result.bin' in the ganessa work directory.
Binary result files also contain all data describing the model.
silent=True overrides iverb setting if provided.

HISTORY

optional argument 'retry' added in 1.5.1

10.4. sFunctions/getallminmax [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

getallminmax returns the min, max, average and mindate, maxdate for all objects of the given type

SYNTAX

vec_min, vec_max, vec_avg, vec_tmin, vec_tmax = getallminmax(typelt, attr)

ARGUMENTS

int typelt: type of element (LINK, NODE, TANK)
string attr: attribute (result) for which value is requested

RESULT

float[] vec_min, vec_max, vec_avg: min, max and avg values for all Elements
float[] vec_tmin, vec_tmax: vector of instants where the min, max value is reached

10.5. sFunctions/hstepcount, tslen,
mslen, tsval,
msval, tsvalbymts,
tsinterv, refdate [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

hstepcount: returns the number of user time steps
tslen, mslen: return number of Elements in the time serie
tsval, msval: return the time series of results and measurements
tsvalbymts: return the time series of results at measurement time steps for a given element type, id and attribute
refdate: return date corresponding to the beginning of simulation

SYNTAX

hsc = hstepcount()
len = tslen()
len = mslen(typelt, id, attr)
vec_tim, vec_val, len = tsval(typelt, id, attr, [interval])
vec_tim, vec_mes, len = msval(typelt, id, attr, [interval])
vec_tim, vec_val, len = tsvalbymts(typelt, id, attr)
tmin, tmax, len = tsinterv()
sdate = refdate()

ARGUMENTS

int typelt: type of element
string id: id of element
string attr: attribute (data or result) for which value is requested
float interval (optional): if present, requests the time serie at given fixed interval in seconds

RESULT

int hsc: number of user time steps
int len: number of values for the time serie
float[] vec_tim: vector of instants in seconds
float[] vec_val: vector of simulated results at the instants vec_tim
float[] vec_mes: vector of measurements at the instants vec_tim
float tmin and tmax: first (vec_tim[0]) and last (vec_tim[-1]) instants available in the result time series
string sdate: date time at beginning of the simulation (iso format)

REMARKS

The time vector is identical for simulation results of all Elements of all types , and can be much larger than the number of (user) time steps
two consecutive instants in the time vector for simulation results may be identical at time step boundaries, change status instants etc.
Each element may have a different measurement time vector form the others
Measurements time series may have different begin and end dates from results
Add 'sdate' in order to get absolute date time
hstepcount requires version 2016 or higher of Piccolo/Ganessa dll

HISTOTY 12/12/2016 (1.5.1): bug fix when no simulation result available

10.6. sFunctions/inv_summary [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

SYNTAX

iter, iter100, fobjmin, fobj100, fobj0, flambda = inv_summary()

ARGUMENTS

NONE

RESULT

int iter: number of iterations
int iter100: number of iterations required to get 1.01 * min
float fobjmin: minimum value of misfit function
float fobj100: misfit function at iteration iter100
float fobj0: misfit function before fitting
float flambda: Levenberg-Marquardt multiplier

REMARK

inv_summary requires version 2016 (160309) or higher of Piccolo/Ganessa dll

HISTORY

new in 1.3.4

10.7. sFunctions/msmooth [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

Defines the smoothing constant for time series of measurements

SYNTAX

msmooth(twidth)

ARGUMENTS

twidth: characteristic time window for smoothing, in seconds

REMARKS

The smoothing algorithm is a convolution with exp(-(t/twidth)^2).
Best results are expected when twidth is in the order of magnitude or larger than the sampling interval.
call msmooth(0.0) in order to cancel smoothing.

10.8. sFunctions/setWQresultfile [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

Defines the binary result file(s) for WQ simulation.

SYNTAX

setWQresultfile([fnode] , [flink])

ARGUMENTS

str fnode: name of the NODE WQ result file
str flink: name of the LINK WQ result file (optional)

REMARK

if fnode is omitted, either use NONE or flink=filename
this command can be used either before running the simulation, for writing the file(s), or afterwards, in order to choose which result file(s) to browse.

10.9. sFunctions/solveH [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

Runs the simulation at a given instant

SYNTAX

istat = solveH(time [, retry])

ARGUMENT

int or str time: instant to run the simulation - default to 0. if int: time in seconds; if str: time in the format hh:mm[:ss]
bool silent: if set to True, simulation runs without any output. Optional - if False or not set, leaves 'iverb' unchanged.
integer iverb: if provided, controls the amount of output during simulation (SIM IVERB parameter). If not set, leaves 'iverb' unchanged.
bool retry: if set to True, the simulation is run again if it fails because of isolated Nodes. Optional - defaults to False

RESULT

int istat: error status (0 if OK)

HISTORY

added 2017.05.15 - version 1.7.5

10.10. sFunctions/stat_quantiles, stat_duration [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

stat_quantiles and stat_duration returns stat info associated with result TS of a given attribute for all Elements in a selection. raw_stat_quantiles and raw_stat_duration are pass_thru versions where the selection is provided as its type, buffer and length

SYNTAX

quantiles = stat_quantiles(sel, attr, qtl)
duration = stat_duration(sel, attr, sop, threshold)
quantiles = raw_stat_quantiles(typelt, attr, qtl, bufsel, nb)
duration = raw_stat_duration(typelt, attr, sop, threshold, bufsel, nb)

ARGUMENTS

string sel: selection of Elements for which stats are expected
string attr: attribute over which the stat is computed
float iterable qtl: quantiles to be computed (0 <= qtl[i] <= 1)
string sop: comparison operator '<' or '>'
float threshold: comparison threshold (expressed in attribute unit)
int typelt: selection object type
int nb: selection count
int[] bufsel: selection vector of indices

RESULT

float[:,:] quantiles: 2-dim array of quantiles - shape (#sel, #qtl). quantiles[i] is the array of quantiles for the element in position i; quantiles[:, k] is the array of quantile qtl[k] for all Elements
float[:] duration: array of cumulated duration (att sop threshold) - shape (#sel, ).

The functions return an empty list if the selection or qtl is empty .

EXAMPLE

cd = stat_duration('BRANCH (d > 500) end', 'V', '>', 0.7)
qtl = stat_quantiles('BRANCH (d > 500) end', 'V', [0.5, 0.95, 1.0]) will return median, 95% quantile and maximum for velocity.

REMARK

Allowed attributes are:

Links: flow (Q), velocity (V), head loss (PC / HL), gradient (GR)
Nodes: Head (HH / CH), pressure (P) and pipe pressure (PP)
Tanks: level (NC / CL), height (H), volume (CV / VC), volume percentage (V%), flow (Q), filling flow (IQ / QR), draught flow (OQ / QV),
all: water quality attributes T, C0 ... C9.

HISTORY

new in 1.5.0 (161124) - should be compatible with 2016b kernel.
1.8.0 (170908): added raw_stat_quantiles and raw_stat_duration

10.11. sFunctions/tsdemand, tsdevice,
tsdemandlen, tsdevicelen [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

tsdemandlen: returns the number of values in the profile
tsdevicelen: returns the number of values in the device state TS
tsdemand: return the profile time series
tsdevice: return the device state time series(boundary conditions)

SYNTAX

tslen = tsdemandlen(code)
vec_tim, vec_val, len, mode = tsdemand(code)
tslen = tsdevicelen(sid[, attr])
vec_tim, vec_val, len, mode = tsdevice(sid [, attr] [, fixed_interval])

ARGUMENTS

string code: demand type of element
string sid: device element ID
string attr: pump attribute (speed or number of units) or ''
float fixed_interval (optional): if present and > 0, return values at the give time step

RESULT

int tslen: number of values for the time serie (0 if NONE)
float[] vec_tim: vector of instants in seconds
float[] vec_val: vector of demand coefficients (not percentages) or settings (for pumps: 0= off, 1 or higher= open/active)
int mode: type of demand profile (<0 as time series, >0 based on time steps)

REMARKS

These functions require version 2016 or higher of Piccolo/Ganessa dll
when the demand code or equipment does not exist or has no forcing TS associated, the value (NONE, NONE, 0, 0) is returned.
The demand coefficient for the demand type 'code' can be retrieved as float(getvar('coefficient:' + code))
A pump is shut off when the number of units running is 0, even if rotation speed is > 0.

HISTORY

25.01.2017: added 'fixed_interval' parameter to tsdevide; changed return value to float

11. ganessa.sim/sIterators [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Iterators available to ganessa.sim ONLY

11.1. sIterators/Dynamic_Stats [ Iterator ]

[ Top ] [ sIterators ] [ Iterator ]

PURPOSE

Iterator which returns stat info associated with result TS of a given attribute for all Elements in a selection in turn.

SYNTAX

for id, retval in Dynamic_Stats(sel, attr [, quantile= qtl] [, duration= (sop, threshold)]):

ARGUMENT

string sel: selection
string attr: attribute
float iterable qtl: quantiles to be computed (0 <= qtl[i] <= 1)
string sop: comparison operator '<' or '>'
float threshold: comparison threshold (expressed in attribute unit)

RESULT

Returns the id and type of each element in the selection in turn:

string id: id of the next element in the selection
retval: result of the requested stat.

The return value depends on the input parameters:

if duration= (sop, threshold) is present, returns the cumulated duration for which attribute (sop) threshold.
if not, if quantile= qtl is present, returns a numpy array of the quantiles for the element id.
without duration and quantile keywords, the return value is [minval, maxval, avg] over the result TS.

REMARK

HISTORY

new in 1.5.0 (161124) - should be compatible with 2016b kernel.

11.2. sIterators/getMinMax [ Iterator ]

[ Top ] [ sIterators ] [ Iterator ]

PURPOSE

Returns the id, min, max, avg value reached by the attribute for each object of the given type or selection in turn

SYNTAX

for id, vmin, vmax, vavg in getMinMax(typelt or selection, sattr):

ARGUMENT

int typelt: type element Constants BRANCH, NODE, RESERVOIR
string selection: name of a selection
string attr: attribute (result) for which value is requested

RESULT

id, vmin, vmax, vavg: str element id, minimum, maximum and average values for the attribute over the simulation

12. ganessa.sort/About [ Introduction ]

[ Top ] [ Introduction ]

PURPOSE

The module ganessa.sort provides sorting functions and Classes used by the Ganessa tools.

13. ganessa.sort/sClasses [ Introduction ]

[ Top ] [ Introduction ]

13.1. sClasses/HeapSort [ Objects ]

[ Top ] [ sClasses ] [ Objects ]

SYNTAX

hs = HeapSort([key]): creates the heap structure.

Instances provide the following methods:

hs.remove(item): removes item - raise KeyError if not found
item, rank = hs.pop(): removes and returns the item of lowest rank.
hs.push(item [, rank]): inserts or replace item with given rank. If the item is already present, its rank and position are updated.
hs.update(item [, rank]): same as push but does nothing if rank unchanged
hs.update_if_lower(item [, rank]): same as push but does nothing if new rank is higher or equal than the actual rank.
hs.update_if_higher(item [, rank]): same as push but does nothing if new rank is lower or equal than the actual rank.
count = len(hs): returns the item count in the heap structure

ARGUMENTS

optional function key: function allowing to compare items being inserted
item: item to be pushed / popped
number rank (optional if key function has been provided to the constructor): defines the ordering of items

RESULT

hs: HeapSort class member
int count: remaining item count in the heap structure.

HISTORY

Introduced in 1.8.2 (171031)

14. ganessa.th/tFunctions [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Functions available to ganessa.th ONLY

14.1. tFunctions/symmetric_node [ Fonctions ]

[ Top ] [ tFunctions ] [ Fonctions ]

SYNTAX

ids = symmetric_node(sid)

ARGUMENTS

string sid: NODE ID for which the symmetric (counterpart NODE on the other circuit) is looked for

RESULT

string sid: id of the counterpart NODE. '' if not found.

REMARKS

always returns '' with Piccolo/Ganessa_SIM
the counterpart can be found only if the hot and cold circuits are almost symmetric
symmetric_node requires version 2016B (160511) or higher of Picalor/Ganessa TH dll

HISTORY

new in 1.3.6

15. ganessa.util/About [ Introduction ]

[ Top ] [ Introduction ]

PURPOSE

The module ganessa.util provides useful functions used by the Ganessa tools.

REMARK

Some of the functions must be preceded by 'import ganessa.sim'

16. ganessa.util/functions [ Introduction ]

[ Top ] [ Introduction ]

16.1. functions/decode_time, decode_date [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

fval = decode_time(input_tstring [, factor])
dval = decode_date(input_dstring)

ARGUMENT

string input_tstr: duration in the form of float or hh:mm:ss or XML duration string.
optional float factor: multiplier (default to 1)
string input_dstr: date in a versatile format YYYY/MM/DD hh:mm:ss or DD/MM/YYYY hh:mm:ss or the iso format YYYY-MM-DDThh:mm:ss where 'T' can be replaced with a blank ' '.

RESULT

float fval: number of seconds. The result is multiplied by factor only if input_string is a float.
date dval: date. The exception 'ValueError' is raised if the date cannot be read.

16.2. functions/dist_to_poly, dist_p_seg,
dist [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

PURPOSE

Computes the distance of a point (xn, yn) to a polyline or a segment

SYNTAX

d, s1, s2 = dist_to_poly(xn, yn, xpoly, ypoly)
d, s, slen = dist_p_seg(xn, yn, x1, y1, x2, y2)
d = dist(x1, y1, x2, y2)

ARGUMENTS

double xn, yn: point coordinates
double[] xpoly, ypoly: vertices of the polyline (number of vertices in the polyline >= 2; 2 for a plain segment)
double x1, y1, x2, y2: coordinates of a segment extremities

RESULT

double d: distance of point to the polyline or segment
double s1, s2: curvilinear position of the point projection on the polyline, from each extremity
double s: curvilinear position of the point projection on the segment, starting from (x1, y1)
double slen: length of the segment (x1, y1), (x2, y2)

REMARKS

d= 0 means that the point is on the polyline.
s1>0 and s2>0 means that the point projection is at least on one of the segments.

HISTORY

1.7.1 (170223) introduced compiled versions of these 3 functions; pure python versions names are prefixed with '_'

16.3. functions/envoi_msg [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

status = envoi_msg(exp, dst, objet, texte [, serveur=smtp.safege.net] [, pwd=NONE])

ARGUMENT

string exp: adresse expediteur du message
string dst: adresse destinataire (ou [dst1, dst2 ... ])
string objet: objet
string texte: texte du message
string serveur (optionnel): serveur d'envoi

RESULT

bool status: True si le message est parti sans erreur

HISTORY

171201: added pwd kwarg

16.4. functions/FichInfo, banner [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

fi = FichInfo(filename)
txt = fi.banner()

ARGUMENT

string filename: input file name - expects the name of the caller '__file__'

RESULT

a class member containing the following fields and method:

nom: basename of the input filename without extension
vers: date of last modification of filename in the form 'YYMMDD'
pyvers: current version of python 'x.y.z'
banner() returns a string containing all the Elements above

16.5. functions/formatting: strf3, stri,
hhmmss, strd,
quotefilename [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

txt = strf3(fval)
txt = stri(ival)
hms = hhmmss(val)
dmy = strd(dval)

ARGUMENT

int or float val: number of seconds
int ival: integer input value
float fval: float input value
date dval: datetime input value

RESULT

string txt: string representation of the input value
string hms: representation of time in the form 'hh:mm:ss'
string dmy: date time in the isoformat except TZ: YYYY-MM-DDTHH:MM:SS

REMARK

The value 'fval' is rounded before conversion

16.6. functions/get_proxy [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

proxy = get_proxy([folder= NONE] [, default_proxy= ''])

ARGUMENTS

optional string folder: folder to search for proxy .json file
optional string default_proxy: default value for proxy

RESULT

string proxy: value of the proxy, False if not found

REMARKS

The .json configuration files are searched for either a "proxy" key or the first element of the first list. Files names are: 'https_proxy', 'Mise_a_jour_packages', 'proxy'.

HISTORY

1.8.8 (171212) created get_proxy

16.7. functions/gfloat, gint,
gbool [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

fval = gfloat(input_string)
ival = gint(input_string)
bval = gbool(input_string)

ARGUMENT

string input_str: string value to be converted to a float or int or bool. The decimal separator can either be '.' or ','.

RESULT

float fval or int ival: numerical value after conversion
bool bval: semantic boolean value. Unlike bool builtin, gbool('False'), gbool('n') and gbool('0') return False

HISTORY

171127: gbool added

16.8. functions/IniFile, get,
set, getall,
setall, save [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

mycfg = IniFile(filename)
txt = mycfg.get(group, key, default)
obj = mycfg.getall(group)
mycfg.set(group, key, value)
mycfg.set(group, obj)
mycfg.save()

ARGUMENT

string filename: input file name - expects the name of the caller '__file__' in order to get the same file path and name with extension .json
string group: group of keys
string key, value: value of key to be stored/retrieved
object obj: object to be stored; may be a DICT of lists.

RESULT

mycfg = IniFile(filename): loads the init file and returns the groups of keys
val = mycfg.get(group, key, val) allows to update val if the value of group/key is defined.
object obj: object retrieved.
set() allows to set key with value
save() saves the files back

HISTORY

Default format changed from .xml to .json in aug 2017; previous settings will be converted.
getall and setall added in march 2018.

16.9. functions/is_text, ascii,
unistr, str2uni,
utf2uni, con2uni [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

bret = is_text(input_str)
atxt = ascii(input_str)
utxt = unistr(input_str)
utxt = str2uni(input_str)
utxt = utf2uni(input_str)
utxt = con2uni(input_str)

ARGUMENT

input_str: value to be converted. Can be of any type: non text input are first converted to unicode.

RESULT

bool bret: indicator telling if the object item is a string (unicode or byte). Equivalent to isinstance(input_str, basestring) in python 2.7
unicode or string atxt: string of same type as input_str where non-ascii charcacters have been replaced with the best match (i.e. 'é' is replaced with 'e').
unicode utxt: unicode string decoded from input_str (multiple codecs tried in turn); unistr tries 'cp1252', 'utf-8', 'cp850', 'iso-8859-1'; str2uni tries 'utf-8', 'cp1252', 'cp850', 'iso-8859-1'; tostr acts as unistr in python2 and as str2uni in python3; con2uni tries cp850 then tostr.

HISTORY

in version 1.9.0, those functions are defined separately for python2 and python3.
since version 1.9.1, the definitions have been merged.

16.10. functions/layout [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

PURPOSE

Determines the number of pages, lines and columns of a figure

SYNTAX

npages, nlines, ncols = layout(nbplots [, nlmax=6 ] [, ncmax= 4])

ARGUMENT

int nbplots: number of Graph to plot
int nlmax (optional, default 6): max nb of graphs per column
int ncmax (optional, default 4): max nb of graphs per line

RESULT

int npages: number of pages to plot
int nlines: number of lines per page
int ncols: number of columns per page

EXAMPLE

nf, nl, nc = layout(len(mes))
for i in range(nf):
plotmes(graphs[i*nl*nc:(i+1)*nl*nc] , ...)

16.11. functions/lec_csv [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

header, content = lec_csv(filename [, sep=','] [, skip_before=0] [, skip_after=0] [, as_tuple=False])

ARGUMENT

string filename: input file name
string sep: optional column separator. Default ','.
int skip_before: optional number of lines to be skipped before reading header.
int skip_after: optional number of lines to be skipped after reading header.
bool as_tuple: optional bool indicating if records are lists (default) or tuples.

RESULT

header: list/tuple of strings read from the 1st line
content: list of lines, each being a list/tuple of text fields

REMARK

The entire file is read into 'content'

16.12. functions/list2file [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

fname = list2file(idlist [, header] [, footer] [, folder] [, suffix])

ARGUMENT

idlist: list of id (unicode str).
header: optional string to be placed before the list
footer: optional string to be placed after the list
folder: optional folder to create the file (default temp folder).
suffix: optional string to be used as a suffix for fname. Defaults to 'IDs.txt'

RESULT

str fname: name of a temporary file containing header if any, Elements of idlist, footer if any, one per line.

16.13. functions/plotmes, plotmesx,
pageplot [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

PURPOSE

plotmes plots one or more time series of the same kind in a single page.
plotmesx plots one or more time series of the same kind on one or more figures. it makes use of layout in order to determine the number of pages.
pageplot plots a Table of time series.
plot_close allows to clean up matplotlib scraps and should be called before the script ends.

SYNTAX

plotmes(mes, attr [, nl=3 ] [, nc=2 ] [, cmt='' ] [, fgname=''] [, inter=True] )
plotmesx(mes, attr [, nlx=6 ] [, ncx=4 ] [, cmt='' ] [, fgname=''] [, inter=True] )
pageplot(tsl, title [, nl=3 ] [, nc=2 ] fgname=''] [, inter=True] [, lang='FR'] )
plot_close()

ARGUMENT

list mes: either a list of element ids, for which the result time series will be retrieved from the result file. If a measurement is associated with an id, it will also be displayed on the same id Graph.
or a list of (id, ftime, fval), in which case the additional time serie (ftime, fval) will be plotted on the id Graph.
list tsl: list of (id, tvec, vvec) to be plotted, one per Graph.
string attr: attribute to be plotted (or attr:DA for residual or attr:DR for relative residual)
ln, cn: number of lines and columns of plots in the page (plotmes only)
lnx, cnx: maximum number of lines and columns of plots in the page (plotmesx only)
cmt: optional comment appended to the title
string fgname: output file name - if not nul, the plot will be saved into a filename with extension '.png'.
bool inter: if False, no plot is displayed

REMARK

Type of data and units are displayed (in french) in the figure title

HISTORY

170426: improvement of x axis labels when time horizon > 24h
170618 (1.7.6): added pageplot
171120 (1.8.5): added plot_close

16.14. functions/roundval, scaladjust [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

PURPOSE

Computes a rounded approximation of a float number

SYNTAX

rmin, rbest, rmax = roundval(val, reltol= 0.01)
rval = scaladjust(val)

ARGUMENT

float val: value to be rounded

RESULT

float rmin, rmax: lower and upper values approximations (rmax - rmin < reltol*|val|)
float rbest: best approximation (one of rmin, rmax)
float rval: value rounded at 1., 2. or 5. in the order of magnitude of val.

REMARK

scaladjust is used to determine the grid interval for plots as scaladjust(0.25*(ymax-ymin))

16.15. functions/toidpic [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

out_str = toidpic(input_str)

ARGUMENT

unicode or string input_str: string value to be converted to a Piccolo ID

RESULT

ascii string where blank, comma, equal are replaced with underscore, other non litteral or digit are replaced with minus.

16.16. functions/update_package [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

stat = update_package(package_name [, minvers=''] [, pypi_name=NONE] [, deps= False] [, https_proxy= NONE])

ARGUMENT

string package_name: name of the package as used in the import statement
optional string minvers: minimum version required, in the form x.y[.z]
optional string pypi_name: package name in pypi, if different from package_name
optional bool deps: set to True to install the dependencies
optional string https_proxy: url and port of the proxy if required.

RESULT

bool stat: true if the package has been installed or updated

REMARKS

minvers can also be provided as a list or tuple of ints
proxy lookup starts with HTTPS_PROXY environment variable, then configuration files lookup using get_proxy() function.

HISTORY

1.8.1 (171009) added
1.8.7 (171208) revised to allow ganessa to update itself
1.8.8 (171212) proxy config .json files lookup added
1.9.1 (180502) python3
1.9.2 (180518) use tempfile for testing access (MT Compatibility)

16.17. functions/winstr, utf,
ws, codewinfile [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

out_txt = winstr(input_str)
out_txt = utf(input_str)
out_str = ws(input_str)

ARGUMENT

unicode or byte string input_str: string value to be encoded to windows-compatible string

RESULT

out_txt encoded into Windows-1252 or utf-8 (no change if no accent or special character)
out_str: (unicode) string in python3, Windows-1252 encoded string in python2

REMARK

codewinfile and winstr are synonyms

HISTORY

ws has been introduced 30.05.2018 - 1.9.3

16.18. functions/XMLduration [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

ival = XMLduration(input_string)

ARGUMENT

string input_str: XML duration string value to be converted to a number of seconds.

The input format is [-]PnYnMnDTnHnMnS where:

leading 'P' is mandatory,
at least one duration item must be present
'T' is mandatory if any hour, minute, second is present
all items are integers except second that may be either int or float.

RESULT

int ival: number of seconds

17. ganessa.util/iterators [ Introduction ]

[ Top ] [ Introduction ]

17.1. iterators/group [ Iterator ]

[ Top ] [ iterators ] [ Iterator ]

SYNTAX

for items in group(iterable, count= 2):

ARGUMENT

iterable: iterable:
int count: group size

RESULT

this iterator allows to return the Elements of iterable grouped by lists of size count. The last list may contain less than group Elements

HISTORY

1.7.6 (170613): iterator added

18. Functions_p/required_cpu [ Fonctions ]

[ Top ] [ Fonctions ]

SYNTAX

ncpu = required_cpu(nb_cpu)

ARGUMENT

int nb_cpu: expected number of parallel processes, up to the hardware core count. A negative or null value indicates the number of hardware cores + nb_cpu.

RESULT

int ncpu: actual number of parallel processes (1 ... max physical core count)

EXAMPLE

required_cpu(-1) returns the hardware core count but one.

TABLE OF CONTENTS

1. ganessa.multithread/Functions_m [ Introduction ]

1.1. Functions_m/mp_run [ Fonctions ]

2. ganessa.parallel/About [ Introduction ]

3. ganessa.parallel/Classes_p [ Introduction ]

3.1. Classes_p/MultiProc, run,run_sequential [ Objects ]

4. ganessa.sim&th/About [ Introduction ]

5. ganessa.sim&th/Classes [ Introduction ]

5.1. Classes/Graph, extrnodes,adjlinks, adjnodes,propagate, dtree [ Objects ]

6. ganessa.sim&th/Compatibility [ Introduction ]

7. ganessa.sim&th/Constants [ Introduction ]

7.1. Constants/BRANCH, LINK,NODE, NOEUD,TANK, RESERVOIR,RSV [ Constants ]

7.2. Constants/DICT [ Constants ]

7.3. Constants/M, NONE [ Constants ]

8. ganessa.sim&th/Functions [ Introduction ]

8.1. Functions/addSHLtype, addSHL,updateSHL, delSHL [ Fonctions ]

8.2. Functions/areas [ Fonctions ]

8.3. Functions/cmd, addcmdw,execute, cmdfile [ Fonctions ]

8.4. Functions/commit [ Fonctions ]

8.5. Functions/cwfold [ Fonctions ]

8.6. Functions/dist2link [ Fonctions ]

8.7. Functions/dll_version, full_version [ Fonctions ]

8.8. Functions/extrnodes [ Fonctions ]

8.9. Functions/gencmd, gencmdw,_gencmdw [ Fonctions ]

8.10. Functions/getall [ Fonctions ]

8.11. Functions/getcodescount, nextcode [ Fonctions ]

8.12. Functions/getdemandbycode, getcodedemandinit,nextcodedemand [ Fonctions ]

8.13. Functions/getid [ Fonctions ]

8.14. Functions/getindex [ Fonctions ]

8.15. Functions/getkeyword, modulekeyword,attrkeyword [ Fonctions ]

8.16. Functions/getvar, getunitname,getunitcoef [ Fonctions ]

8.17. Functions/importEpanet, exportEpanet [ Fonctions ]

8.18. Functions/init [ Fonctions ]

8.19. Functions/linkattr, nodeattr,tankattr, linkattrs,nodeattrs, tankattrs,attr, attrs,meanattr [ Fonctions ]

8.20. Functions/linkbbox [ Fonctions ]

8.21. Functions/linkXYZV, branchXYZV [ Fonctions ]

8.22. Functions/loadbin [ Fonctions ]

8.23. Functions/loadres [ Fonctions ]

8.24. Functions/nbobjects [ Fonctions ]

8.25. Functions/nlinkattr, nnodeattr,ntankattr, nlinkattrs,nnodeattrs, ntankattrs,nattr, nattrs [ Fonctions ]

8.26. Functions/nodeXYZ [ Fonctions ]

8.27. Functions/quit, close [ Fonctions ]

8.28. Functions/reset [ Fonctions ]

8.29. Functions/resfile [ Fonctions ]

8.30. Functions/save, savemodel [ Fonctions ]

8.31. Functions/selectlen, select [ Fonctions ]

8.32. Functions/setbatchmode [ Fonctions ]

8.33. Functions/setlang [ Fonctions ]

8.34. Functions/setlinkattr, setbranchattr [ Fonctions ]

8.35. Functions/shearstr [ Fonctions ]

8.36. Functions/useExceptions, GanessaError,SimulationError [ Fonctions ]

9. ganessa.sim&th/Iterators [ Introduction ]

9.1. Iterators/Branches, Links [ Iterator ]

9.2. Iterators/DemandCodes [ Iterator ]

9.3. Iterators/Demands [ Iterator ]

9.4. Iterators/Elements [ Iterator ]

9.5. Iterators/Nodes [ Iterator ]

9.6. Iterators/Selected [ Iterator ]

9.7. Iterators/Table [ Iterator ]

9.8. Iterators/Tanks, Reservoirs [ Iterator ]

9.9. Iterators/Unstable [ Iterator ]

10. ganessa.sim/sFunctions [ Introduction ]

10.1. sFunctions/browseH, browseWQ [ Fonctions ]

10.2. sFunctions/defcalind, getcalind [ Fonctions ]

10.3. sFunctions/full_solveH [ Fonctions ]

10.4. sFunctions/getallminmax [ Fonctions ]

10.5. sFunctions/hstepcount, tslen,mslen, tsval,msval, tsvalbymts,tsinterv, refdate [ Fonctions ]

10.6. sFunctions/inv_summary [ Fonctions ]

10.7. sFunctions/msmooth [ Fonctions ]

10.8. sFunctions/setWQresultfile [ Fonctions ]

10.9. sFunctions/solveH [ Fonctions ]

10.10. sFunctions/stat_quantiles, stat_duration [ Fonctions ]

10.11. sFunctions/tsdemand, tsdevice,tsdemandlen, tsdevicelen [ Fonctions ]

11. ganessa.sim/sIterators [ Introduction ]

11.1. sIterators/Dynamic_Stats [ Iterator ]

11.2. sIterators/getMinMax [ Iterator ]

12. ganessa.sort/About [ Introduction ]

13. ganessa.sort/sClasses [ Introduction ]

13.1. sClasses/HeapSort [ Objects ]

14. ganessa.th/tFunctions [ Introduction ]

3.1. Classes_p/MultiProc, run,
run_sequential [ Objects ]

5.1. Classes/Graph, extrnodes,
adjlinks, adjnodes,
propagate, dtree [ Objects ]

7.1. Constants/BRANCH, LINK,
NODE, NOEUD,
TANK, RESERVOIR,
RSV [ Constants ]

8.1. Functions/addSHLtype, addSHL,
updateSHL, delSHL [ Fonctions ]

8.3. Functions/cmd, addcmdw,
execute, cmdfile [ Fonctions ]

8.9. Functions/gencmd, gencmdw,
_gencmdw [ Fonctions ]

8.12. Functions/getdemandbycode, getcodedemandinit,
nextcodedemand [ Fonctions ]

8.15. Functions/getkeyword, modulekeyword,
attrkeyword [ Fonctions ]

8.16. Functions/getvar, getunitname,
getunitcoef [ Fonctions ]

8.19. Functions/linkattr, nodeattr,
tankattr, linkattrs,
nodeattrs, tankattrs,
attr, attrs,
meanattr [ Fonctions ]

8.25. Functions/nlinkattr, nnodeattr,
ntankattr, nlinkattrs,
nnodeattrs, ntankattrs,
nattr, nattrs [ Fonctions ]

8.36. Functions/useExceptions, GanessaError,
SimulationError [ Fonctions ]

10.5. sFunctions/hstepcount, tslen,
mslen, tsval,
msval, tsvalbymts,
tsinterv, refdate [ Fonctions ]

10.11. sFunctions/tsdemand, tsdevice,
tsdemandlen, tsdevicelen [ Fonctions ]

16.2. functions/dist_to_poly, dist_p_seg,
dist [ Fonctions ]

16.5. functions/formatting: strf3, stri,
hhmmss, strd,
quotefilename [ Fonctions ]

16.7. functions/gfloat, gint,
gbool [ Fonctions ]

16.8. functions/IniFile, get,
set, getall,
setall, save [ Fonctions ]

16.9. functions/is_text, ascii,
unistr, str2uni,
utf2uni, con2uni [ Fonctions ]

16.13. functions/plotmes, plotmesx,
pageplot [ Fonctions ]

16.17. functions/winstr, utf,
ws, codewinfile [ Fonctions ]