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.

2. ganessa.parallel/About [ Introduction ]

[ Top ] [ Introduction ]

PURPOSE

The module ganessa.parallel provides a multitasking (parallel) computing capability based on multiprocessing Process and Queue objects.

3. ganessa.parallel/Classes_mt [ Introduction ]

[ Top ] [ Introduction ]

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

[ Top ] [ Classes_mt ] [ Objects ]

DESCRIPTION

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.
optionally, func can be a tuple (fun, erfun); erfun(*args) will be called for a return value if fun(*args) raise an exception (added 190416).
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
Updated 2019.04.11: NotImplementedError handling in cpu_count
Updated 2019.04.16: added erfun handling for return value when fun raises an exception

4. ganessa.plot/functions_plot [ Introduction ]

[ Top ] [ Introduction ]

4.1. functions_plot/layout [ Fonctions ]

[ Top ] [ functions_plot ] [ Fonctions ]

PURPOSE

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

SYNTAX

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

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
char orient (optional, default 'h'): orientation of the layout (h or v)

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] , ...)

4.2. functions_plot/plotmes, plotmesx,
pageplot, pageplotx [ Fonctions ]

[ Top ] [ functions_plot ] [ 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] [, orient= 'h'])
plotmesx(mes, attr [, nlx=6 ] [, ncx=4 ] [, cmt='' ] [, fgname=''] [, inter=True] [, orient= 'h'])
pageplot(tsl, title [, nl=3 ] [, nc=2 ] fgname=''] [, inter=True] [, lang='FR'] [, orient= 'h'])
pageplotx(tsl, title [, nlx=3 ] [, ncx=2 ] fgname=''] [, inter=True] [, lang='FR'] [, orient= 'h'])
plot_close()

ARGUMENT

list mes: either a list of element ids, for which the result time series will be retrieved from the result file and plotted in blue. If a measurement is associated with an id, it will also be displayed in red on the same id Graph.
or a list of (id, ftime, fval), in which case the additional time serie (ftime, fval) will be plotted in green on the id Graph as 'Reference'
or a list of (id, ftime, fval1, fval2) or (id, ftime1, fval1, ftime2, fval2) which will be plotted fval1 as 'Reference' (green) and fval2 as 'Alternate' (magenta)
list tsl: list of (id, tvec, vvec [,vvec2]) to be plotted, one per Graph.
string attr: attribute to be plotted (or attr:DA for residual or attr:DR for relative residual)
string title: title for pageplot(x). If tsl contains 2 data series, title can be given as a tuple (title, legend1, legend2).
nl, nc: number of lines and columns of plots in the page (plotmes and pageplot only)
nlx, ncx: maximum number of lines and columns of plots in the page (plotmesx and pageplotx 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
char orient (optional, default 'h'): orientation of the layout (h or v)

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
180924 (2.0.1): added orient kw
181105 (2.0.3): added pageplotx
200103 (2.0.8): plot reference before simulation
200315 (2.1.1): plot chlorine
200603 (2.1.3): single (static) measurement plotted as an horizontal line
200915 (2.1.5): pageplot(x) allows multiple ts per Graph.
210111 (2.1.6): fix an overflow error plotting long TS (> 248 days)
210301 (2.1.7): optionnally plot bottom & top TANK levels ('*' marker)

5. 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) kernel API. It is provided as python wheels:

    - all versions up to version 2.1.9 (april 2021) are compatible with python 2.7.
    - from version 2, it is compatible with 32 and 64 bits versions of python 3.6/3.7.
    - from version 2.1, it is compatible with python 3.7.6 and 3.8.
    - from version 2.1.5, it is compatible with python 3.9.

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

INSTALLATION

python -M pip install [--trusted-host pypi.org] ganessa

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 %LOCALAPPDATA%/Programs folders:

Safege/Ganessa_<lang>/Ganessa_SIM.dll (or Suez/...)
Safege/Piccolo_<lang>/Picwin32.dll (or Suez/...)
Inetum/Piccolo6_<lang>/Picwin32.dll (starting with version 2.2.3)
Gfi Progiciels/Piccolo6_<lang>/Picwin32.dll

or in one of the Program Files (x86) sub folders (Picalor6 replaces Piccolo6 if needed):

"Safege/Ganessa_<lang>/Ganessa_xx" (xx = SIM or TH) or
"Inetum/Piccolo6_<lang>[_ck | _cl]/Picwin32.dll" or
"Gfi Progiciels/Piccolo6_<lang>[_ck | _cl]/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:

determines if it runs in python embedded - cf. is_embedded()
locate Ganessa_xx.dll or Picwin32.dll kernel
initialise it (if not run in embedded python)
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.0: (140211) creation of the package for python 2.7
1.0.3: (140410) plotmesx png takes care of measurement type
1.0.4: (140702) added demand getter for a demand code or for all
1.0.5: (140908) added Windows 7 paths 'program files (x86)'; added option to get TS by measurement step 'tsvalbymts'; added 'refdate' : retireval of refdate
1.0.6: (140908) correction to the grid adjustment in plotmes (util)
1.0.7: (140916) getMinMax can be called with a selection name
1.0.8: (140925) save function
1.0.9: (141006)SimulationError exception catching + save(identical to MMI); requires numpy 1.8.1
1.1.0: (141006) same as 1.0.9 but requires only numpy 1.7.1
1.1.1: (141016) minor change to codewinfile=winstr
1.1.2: (141020) 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) added epanet2 API and dll (py27 only); fix epanet.getlinknodes; (180530) added util.ws
1.9.4 (180531) fix utf-8 decoding for IniFile1L; (180604) fix getindex; added exists
1.9.5 (180607) added epanet2 API and dll (compiled from epanettools 0.4.2); (180608) added an example in README; (180613) plot funcs moved from ganessa.util to ganessa.plot
1.9.6 (180615) fix sim.init handling non-ascii chars in folder name (uploaded 180621)
1.9.7 (180705) fix util.IniFile handling non-ascii chars in file name; (180718) fix OpenFileMMI issue with inidir; (180813) added support for Piccolo 2018 (released 2018-07-25) and uploaded
1.9.8 (180814) 64-bits version for Ganessa_SIM (python 3.6); minor OpenFileMMI changes (clear_exe, bt_exe_state); (180815) upload wheels for python 3.7 (32 and 64 bits).
2.0.0 (180816) util.group fix (python 3.7); added verbose param in util.update_package; (180820) added 'wqtracevectsize' for returning the max size of WQ; concentration vector usable for tracing origin of water; (180823) added geojsonfile for writing to geojson; fix minor midfile issue; (180829) added C:/Program Files lookup in x64 env; geojson reader; (180831) release and upload
2.0.1 (180910) util.list2file minor fix; doc fix; minor Elements changes; (180919) fix ganessa.th break in 2.0.0; (180924) added orient keyword in ganessa.plot functions; slight behavior change
2.0.2 (181003) added util.strf2loc; doc update; (181011) minor change in sim.seleclen; added util.call_until_false; (181025) minor fix in ganessa.prot; (181030) release and upload
2.0.3 (181105) added plot.pageplotx; (13) added '.' at head of prot lookup folders; (181119) changed geojson and midfile to conform to shapefile 2.0; (181203) added '_cl' suffix option to the Piccolo lookup folder; len for Selected, Elements and derived iterators; (181207) fix util.IniFile1L.save with python 3.x; (181209) doc updated; release and upload
2.0.4 (181218) debug mode for unicode control; util.IniFile.get returns ustr; (181220) OpenFileMMI.ExecStatus.clear: remove 'all' kwarg; added len to getMinMax and DynamicStats iterators
2.0.5 (181229) added util.perfs; (190107) handle OpenFileMMI.SelectModel(usedef=False); (190109) changes in update_package permission lookup; (190131) release and (190211) upload
2.0.6 (190411) minor fix in parallel.required_cpu; (190416) minor evolution to parallel.MultiProc: alternate erfun call on Exception; (190423) release and upload
2.0.7 (190617) added 'extra_data' keyword to sim.savemodel; (190715) added DYNSTOP SimulationError; minor doc fix; (190819) improved simulation error check in full_solveH, solveH, solveTH; (190821) added util.get_python_exe; (191007) minor fix in OpenFileMMI.SelectFile; (191008) release and upload
2.0.8 (191015) fix README.rst; (200106) added upstream and downstream methods to sim.Graph; (200204) fix new python 3.8 dll directory search; release and upload (2.7-32 / 3.7 / 3.8 only)
2.0.9 (200205) fix prot with python 3.8 dll directory search + minor changes; release and upload (2.7-32 / 3.7 / 3.8 only)
2.1.0 (200214) fix urllib3 requiring proxy scheme in get_proxy; (200220) Piccolo versions 2017+ required for python 3.x+; fix to dll directory search, related to FlexLM; fix Example.py; release and upload (2.7-32 / 3.7 / 3.8 only)
2.1.1 (200306) new sim.WQSources() iterator; (200313) fix util.scaladjust for range below 1; fix chlorine (C1) plot.plotmes(x); (200314) add added util.is_wq and sim.wqtslen; fix sim.tsval for WQ TS; (200323) doc fixes; add module constant KW (MOD kw, QUA, INV); add optional return_type=True kw to sim.Selected; (200324) fix workdir & result file in virtualstore; release and upload (2.7-32 / 3.7 / 3.8 only)
2.1.2 (200506) add util.IniFile.remove; (200511) release and upload (2.7-32 / 3.7 / 3.8 only)
2.1.3 (200603) plot.plotmes: single (static) measurement plotted as an horizontal line; (200604) OpenFileMMI.SelectModel: chdir to model folder to allow relative inner read; (200619) added en2emu sim-like minimal Compatibility module; (200622) added nbvertices() and fake get_labels(); (200629) release and upload (2.7-32 / 3.7 / 3.8 only)
2.1.4 (200708) dll lookup in '.'; (200819) minor fix on plot.pageplot; release and upload (2.7-32 / 3.7 / 3.8 only)
2.1.5 (200824) replace util.ascii with util.myascii; (200915) plot.pageplot(x) allows multiple ts per Graph; fix cmdfile; (200922) added demand profile query by zone and code/zone (tsdemand); (201109) added util.read_as_idpic; (201119) release and upload (2.7-32 / 3.7 / 3.8 only)
2.1.6 (201221) fix prot error with null path chunks; (201222) fix Ganessa_TH integration not working properly; (210126) added util.split_poly_at; release and upload
2.1.7 (210301) plot.plotmes(x) plot TANK bottom and top water level when prefixed with '='; (210307) addl single value plot as horizontal line in plot.pageplot; (210310) add util.utf8_bom_encoding(file); (210324) fix util.split_poly_at ValueError: not enough values to unpack (expected 3, got 2); release and upload (2.7-32 / 3.7 / 3.8 only)
2.1.8 (210325) added Graph.pop and len(Graph); added SelectModel.update_info; fix missing .pyd components resulting in suboptimal use of the API; release and upload (2.7-32 / 3.7 / 3.8 / 3.9)
2.1.9 (210426) util.IniFile removes the -<maxvers><minvers> suffix on param save; (210428) prot now seek extensive paths incl. ../SafProdLicMgr, C:/Logiciels etc.; (210429) fix geojson writer (use Transformer, swap return coords); (210430) release and upload (2.7-32 / 3.7 / 3.8 / 3.9) - last 2.7 release
2.2.0 (210506) fix pypi doc; change _fresult and _workdir lookup; (210517) minor changes to util.strf3 and strf2 (210527) fix Ws10 using utf8 rather than cp1252 in util (210531) release and upload (3.7 / 3.8)
2.2.1 (210609) util.send_report include OS version (210610) OpenFileMMI.SelectFile: invisible contour & parent cascade for subframe (210614) Add %localappdata%/Programs/Safege & Suez... to the search path (210616) Add Inetum to the lookup folders for Piccolo (210617) Add update_info(-1) to OpenFileMMI.SelectFile (210618) release and upload (3.7 / 3.8); (210621) upload (3.9) - not passed
2.2.2 (210621) Add %localappdata%/Programs/Gfi Progiciels & Inetum to the search path (210621) fix README.rst; release and upload (3.7 / 3.8 / 3.9);
2.2.3 (210623) Minor fix to OpenFileMMI.SelectModel.update_info(-1); (210624) Added IsolatedNodeSimulationError exception; (210701) lookup 'Inetum' folder before 'Gfi Progiciels'; addl TS for plot.plotmes (210702) release and upload 32 (3.5 / 3.6 / 3.7 / 3.8) and 64 (3.7 / 3.8)
2.2.4 (210705) fix dll search path order with D: partition (210723) OpenFileMMI.SelectModel silent read .dat by default (210819) Handling of python embedding into dll caller (Piccolo.exe) - beta (210823) add sim.is_embedded() (210901) add sim.dll_version() from API = not requiring init(); release and upload (3.8 / 3.9)
2.2.5 (210913) adaptation to python 3.10; (210914) plot changes (uses- axes and figures rather than default pyplot funcs); (210927) fix util.get_proxy doc and return value; (210929) fix getvar truncate output to 48 (now 256); add model_filename(); util.update_package exits in embedded mode. (211004) OpenFileMMI.SelectModel kwarg show_emb=False hides dialog in embedded mode; (211012) util.IniFile kwarg folder=NONE allows load/save to alternate location; (211013) OpenFileMMI.SelectModel fix chdir error when filename has no dirname; (211020) add OpenFileMMI.SelectFile.setfilename; (211026) add fname property to OpenFileMMI.SelectFile, SelectModel, SelectFolder; (211027) release and upload (3.8 / 3.9 / 3.10)
2.2.6 (211028) add OpenFileMMI.SelectFolder.add_extra_info; .fname setter (211106) add type hint to most functions (211109) fix _dll_version in embedded mode (211112) add emb_model_folder() function (211116) minors changes in OpenFileMMI; new util.piccolo_context function for color settings (211117) release and upload (3.8 / 3.9 / 3.10)
2.2.7 (211124) fix is_wq() for water hardness (TH or HD or DU); setlang accepts 1 or 2 letter arg (211126) OpenFileMMI.add_extra_model_info append to previous line if returned text starts with backspace \b (211216) refdate returns (unicode) str (211230) release and upload (3.8 / 3.9 / 3.10)
2.2.8 (220128) fix util Compatibility with windows servers (220203) dll lookup on E: if it exists and D: does not (220203) release and upload (3.8 / 3.9 / 3.10) (should have done it yesterday !)
2.2.9 (220211) fix non ascii str passed to Selected must be bytes (220214) fix util.update_package: replace -use-binary with -prefer-binary; -trusted-host pypi.org (220222) release and upload (3.8 / 3.9 / 3.10)

           postponed: <<add epanet 2.2.0 API as _epanet22 - same interface as _epanet2>>.

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

[ Top ] [ Introduction ]

DESCRIPTION

Classes available to ganessa.sim and ganessa.th

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

[ Top ] [ Classes ] [ Objects ]

SYNTAX

Graph = Graph([orientation])

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
pairs = Graph.adj_links_nodes(NODE): return a set of (LINK, Nodes) tuples
LINK, from_n, to_n = Graph.pop(): remove a LINK and returns it wih from and to Nodes
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
linkset, nodeset = Graph.downstream(anode [, update='Q'] [, maxlen= -1]): returns downstream Elements with respect to 'update' attribute direction (default Q)
linkset, nodeset = Graph.upstream(anode [, update='Q'] [, maxlen= -1]): returns upstream Elements with respect to 'update' attribute direction (default Q)

ARGUMENTS

str orientation: the attribute sign will be used for orienting the Graph. (default NONE, orientation from -> to)
str alink, anode: LINK, NODE ID
int maxlen: compute Graph propagation up to maxlen steps (<0 if not limited)
str update: attribute to be used as LINK direction (defaut 'Q'; use '' or NONE to disable direction update)

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
reviewed 2.0.8 (200106): added revert, upstream, downstream discard degenerated Links (same from and to NODE) changed internal representation
reviewed 2.1.8 (210325): added pop and __len__

7. 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 - 1.9.6)
2018 -> 180725 Piccolo6 & Picalor6 -- release 2018 (1.9.7 - )
2020 -> 200306 Piccolo6 & Picalor6 -- release 2020 (2.1.1 - )
2021 -> 2103xx Piccolo6 & Picalor6 -- release 2020b (2.1.1 - )

REMARK

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

8. 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

8.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

8.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

8.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.

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

[ Top ] [ Introduction ]

DESCRIPTION

Functions available to ganessa.sim and ganessa.th

9.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

9.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.

9.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

HISTORY

1.9.6 (180615): convert str to cp1252
2.1.5 (200915): extend cmdfile to allow cmdfile(file, arg1, arg2, ..)

9.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

9.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) * 1.9.6 (180615): fix non-ascii folder str converted to cp1252

9.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)

9.7. Functions/dll_version, full_version [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

yyyymmdd = dll_version()
text = full_version()

RESULT

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

REMARK

Starting with 2.2.4 (210901), if called before init(), dll_version() will return the version if the .dll is newer than 210831, 0 otherwise.

HISTORY

dll_version introduced in 1.8.0 (170907)
full_version introduced in 1.8.6 (171201)
returns api.dll_version() if defined (210901)

9.8. Functions/extrnodes [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

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

SYNTAX

i_from, i_to = extrnodes(i_link)

ARGUMENTS

int i_link: index of the LINK

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.

9.9. Functions/gencmd, gencmdw,
raw_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

9.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.

9.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.

9.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(nid, code)
nbpairs = getcodedemandinit(nid)
code, demand, codelen = nextcodedemand()

ARGUMENTS

string nid: 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(nid) iterator

HISTORY

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

9.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.

9.14. Functions/getindex, exists [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

num = getindex(typelt, sid)
bret = exists(typelt, sid)

ARGUMENT

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

RESULT

int num: index of element ID (starting at pos 1)
bool bret: indicates if the element exists in the model

HISTORY

getindex new in 1.3.3 but not working !
getindex fixed in 1.9.4 (180604)
exists created in 1.9.4 (180604)

9.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.

9.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.

9.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.

9.18. Functions/init [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

init([folder] [, silent=False] [, debug=False])

ARGUMENT

str folder: optional folder name where journal and work files will be created silent: if set to True, most information and warning message will not show

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
1.9.6 (180615): fix non-ascii folder str converted to cp1252

9.19. Functions/is_embedded [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

ret = is_embedded()

RESULT

bool ret: indicates whether python is embedded or not

HISTORY

introduced in 2.2.4 (210823)

9.20. 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.

9.21. 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)

9.22. 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.

9.23. 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.
The filename is quoted if necessary

9.24. 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.

9.25. 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

9.26. Functions/nbvertices [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the number of Links with vertices (bends)

SYNTAX

nb = nbvertices()

RESULT

int nb: number of Links with vertices

9.27. 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.

9.28. 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

9.29. 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()

9.30. Functions/reset [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Clears (removes) all model objects

SYNTAX

istat = reset()

RESULT

int istat: error status (0 if OK)

9.31. Functions/resfile, res_filename,
model_filename [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

Returns the name of the default binary result file; the model filename.

SYNTAX

name = resfile() name = res_filename() name = model_filename() folder = emb_model_folder()

RESULT

str name: file name or '' if undefined str folder: folder if called from embedded python or '' if not

HISTORY

170919 (1.8.0) Introduced
210929 (2.2.5) Added res_filename and res_filename
211112 (2.2.6) Added emb_model_folder

9.32. Functions/save, savemodel [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

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

ARGUMENTS

string fname: file name to save to
string version: optional version string "x.yz" for writing compatible file format, for text file only.
list extra_data: list of (selection, attribute_keyword) to be saved. Selection is a string describing a valid selection at save time; attribute_keyword is a string name of a valid attribute for import, such as XX, YY, ZZ, K (Links), Z (Nodes). Multiple attributes can be provided separated by blanks.

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.

EXAMPLE

savemodel('myModel.dat', version='3.95', extra_data=[('NOEUD', 'YY ZZ')])

HISTORY

190617: added extra_data keyword parameter to savemodel (2.0.7)

9.33. 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

9.34. 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)

9.35. 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) reviewed 2.2.7 (211124) : accepts new_lang with at least 1 letter

9.36. Functions/setlinkattr, setbranchattr,
setnodeattr [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

istat = setlinkattr(id, attr, val)
istat = setnodeattr(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/NODE
-1 if the attribute is not recognised
-2 if the LINK/NODE does not exist

REMARKS

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

HISTORY

setlinkattr is a synonym that has been introduced as 22/09/2016
setnodeattr has been introduced on 22/06/2020 (2.1.3)

9.37. 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)

9.38. Functions/useExceptions, GanessaError,
SimulationError, IsolatedNodeSimulationError [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

SYNTAX

oldstat = useExceptions([status])
try: ... except GanessaError:
try: ... except SimulationError [as exc]:
try: ... except IsolatedNodeSimulationError [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. IsolatedNodeSimulationError is a derived class of SimulationError, thrown when a simulation error originates form isolated Nodes.

The simulation error subtypes (exc.reason) 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.DYNSTOP: The simulation did not complete
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.

HISTORY

190715: added SIMERR.DYNSTOP
210624: added IsolatedNodeSimulationError

9.39. Functions/wqtracevectsize [ Fonctions ]

[ Top ] [ Functions ] [ Fonctions ]

PURPOSE

wqtracevectsize returns the max count of water quality concentrations allowed, including chlorine (C1).

SYNTAX

n = wqtracevectsize()

RESULT

int n: max count

REMARK

One may expect a return value of either 9 (C1 .. C9) or 45 (C1 .. C9 + $0 .. $9 + $A .. $Z).

HISTORY

introduced 2.0.0 (180820)

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

[ Top ] [ Introduction ]

DESCRIPTION

Iterators available to ganessa.sim and ganessa.th

10.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.

10.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

10.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.

10.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 (2018/04/05) ids are returned as unicode strings. From version 2.0.3 (2018/12/03) len Compatibility with python3

10.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.

10.6. Iterators/Selected [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

SYNTAX

for id, typelt in Selected(sname [, return_type=True]):

ARGUMENT

string sname: name of a selection bool return_type: if False, the type is not returned (default True)

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), if return_type is True

HISTORY

2.0.3 (2018/12/03) len Compatibility with python3
2.1.1 (2020/03/20) add return_type optional keyword argument
2.2.9 (2022/02/11) convert string to ansi for Piccolo cmd language

10.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.

10.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.

10.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.10. Iterators/WQSources [ Iterator ]

[ Top ] [ Iterators ] [ Iterator ]

PURPOSE

Provide access to the sequence of source items

SYNTAX

for NODE, code, attr, tvec, cvec, nvec in WQSources(NODE=NONE):

ARGUMENTS

string NODE: specific NODE to look for, or '' for all Nodes.

RESULT

Returns each source boundary condition in turn:

string NODE: NODE ID
string code: code associated to the source (or '' if forcing)
string attr: WQ attribute (T, C0 ... C9, $0 ... $9, $A ...$ Z)
float tvec[], cvec[]: time and quantity vector (time serie)
int nvec : TS size

If NODE is given (non blank string):

if it exists, data will be returned for this NODE only
if the NODE does not exists, the return sequence is empty

If the NODE is not given, all WQ data will be returned

REMARK

WQSources requires version 2020 (200306) or higher of Piccolo/Ganessa dll

HISTORY

new in 2.1.1

11. ganessa.sim/sFunctions [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Functions available to ganessa.sim ONLY.

11.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)
istat = browseWQ(time_step)
istat = browseWQ(instant)

ARGUMENTS

int time_step: time step to load (seconds)
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.

11.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.

11.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 twice 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

1.5.1: optional argument 'retry' added
2.0.7: improved error check (19/08/19)
2.2.3: retry=True retries the simulation twice, in case STOP-ON-APP is OFF (26/06/21)

11.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

11.5. sFunctions/hstepcount, tslen,
mslen, tsval,
msval, tsvalbymts,
tsinterv, wqtslen,
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()
len, tmax = wqtslen(typelt)
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 15/03/2020 (2.1.1): added wqtslen; fix tsval for WQ ts

11.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

11.7. sFunctions/msmooth [ Fonctions ]

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

Defines the smoothing time width 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.

11.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.

11.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
changed 2019.04.23 - version 2.0.6 - added a third retry
changed 2019.08.19 - version 2.0.7 - improved error check

11.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

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

[ Top ] [ sFunctions ] [ Fonctions ]

PURPOSE

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

SYNTAX

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

ARGUMENTS

string code: demand type of element
string zone: area 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
Demand zones require version 2020b or higher
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
22.09.2020: added the query of demand profile by zone

12. ganessa.sim/sIterators [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Iterators available to ganessa.sim ONLY

12.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.
181220: added __len__

12.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

HISTORY

181220: added len method

13. ganessa.sort/About [ Introduction ]

[ Top ] [ Introduction ]

PURPOSE

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

14. ganessa.sort/sClasses [ Introduction ]

[ Top ] [ Introduction ]

14.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)

15. ganessa.th/tFunctions [ Introduction ]

[ Top ] [ Introduction ]

DESCRIPTION

Functions available to ganessa.th ONLY

15.1. tFunctions/solveTH [ Fonctions ]

[ Top ] [ tFunctions ] [ Fonctions ]

PURPOSE

Runs the thermo-hydraulic simulation

SYNTAX

istat = solveH([silent=False [, iverb=-1 [, retry=True]]])

ARGUMENTS

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
changed 2019.08.19 - version 2.0.7 - improved error check

15.2. 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

16. 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'

17. ganessa.util/functions [ Introduction ]

[ Top ] [ Introduction ]

17.1. functions/call_until_false [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

PURPOSE

Calls a function with args until return is false

SYNTAX

res = call_until_false(func, args [, maxcount= -1])

ARGUMENT

callable func: function to be called with args
args: *args to func
int maxcount: optional max count (defaults to -1: infinite sequence)

RESULT

tuple of sucessive return values

REMARK

Use of this function is meaningful with side-effect functions. The function is repeatedly called with the same argument list; the result is not just duplicated.

HISTORY

introduced 2.0.3 (1801011)

17.2. 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.

17.3. functions/dist_to_poly, dist_p_seg,
dist, split_poly_at [ 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, nbpoly, xpoly, ypoly)
d, s1, s2 = dist_to_poly(xn, yn, points)
d, s, slength = dist_p_seg(xn, yn, x1, y1, x2, y2)
d = dist(x1, y1, x2, y2)
k, xsplit, ysplit, totlen = split_poly_at(xpoly, ypoly, s, nbpoly)

ARGUMENTS

double xn, yn: point coordinates
int nbpoly: number of points
double[] xpoly, ypoly: vertices of the polyline (number of vertices in the polyline >= 2; 2 for a plain segment)
sequence points: sequence of pairs of float or double
double x1, y1, x2, y2: coordinates of a segment extremities
double s: curvilinear position to split at

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 slength: length of the segment (x1, y1), (x2, y2)
int k: rank of splitted segment (0: before or at start; nb: after or at end)
double xsplit, ysplit: coordinates of the scurvilinear position s on the plyline
double totlen: total length of the polyline before splitting

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 '_'
2.1.6 (210126) added split_poly_at
2.1.7 (210324) fix split_poly_at 'ValueError: not enough values to unpack (expected 3, got 2)'

17.4. 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

17.5. 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

HISTORY

180814 (1.9.8): appended '32/64 bits' to banner info

17.6. functions/formatting: strf2, strf3,
strf2loc, strf3loc,
stri, hhmmss,
strd [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

txt = strf2(fval)
txt = strf3(fval)
txt = stri(ival)
hms = hhmmss(val [, rounded=False] [, days=False])
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
bool rounded: round value to the nearest second value
bool or str days: if True and hours >= 24, then writes d<days>hh:mm:ss

RESULT

string txt: string representation of the input value
string hms: representation of time in the form 'hh:mm:ss' or 'd<sep>hh:mm:ss' when days=True and fval >= 86400; <sep> is days if days is a str, otherwise ' '.
string dmy: date time in the isoformat except TZ: YYYY-MM-DDTHH:MM:SS

REMARK

strf2 and strf3: values larger that 1 are written with at most 2 or 3 digits after decimal dot.
strf2loc and strf3loc use the local decimal dot (. or ,).
strd: the value 'val' is rounded to seconds id rounded= True

HISTORY

23/11/2020 (2.1.6): added 'days' keyword to hhmmss.

17.7. functions/get_proxy [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

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

ARGUMENTS

optional string folder: folder to search for proxy .json file
optional string default: 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 2.1.0 (200214) fix urllib3 requiring proxy scheme (http[s]://) 2.1.5 (210927) fix kwarg name default in doc; fix return value

17.8. functions/get_python_exe [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

name = get_python_exe()

RESULT

str name: path/name to the python executable in use, possibly without extension

HISTORY

2.0.7 (190821) created

17.9. 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

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

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

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

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 folder: alternate folder to load from / save to
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. If folder was given and exists, then the file is saved into that folder instead of the filename folder.
remove() returns the mapping or NONE if not found

HISTORY

Default format changed from .xml to .json in aug 2017; previous settings will be converted.
getall and setall added in march 2018.
180705 (1.9.7) IniFile handles non-ascii filenames
181218 (2.0.4) get returns unicode strings
200506 (2.1.2) remove method
210426 (2.1.9) remove trailing '-<maxver><minver>' from the basename
211012 (2.2.5) add folder kwarg

17.11. functions/IniFile1L, get,
set, remove,
save [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

mycfg = IniFile1L(filename)
txt = mycfg.get(key, default)
mycfg.set(key, value)
value = mycfg.remove(key)
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 key, value: value of key to be stored/retrieved

RESULT

mycfg = IniFile1L(filename): loads the init file and returns the keys
val = mycfg.get(key, val) allows to update val if the value of key is defined.
set() allows to set key with value
save() saves the files back
remove() returns the mapping or NONE if not found

HISTORY

210426 (2.1.9) remove trailing '-<maxver><minver>' from the basename
210708 (2.2.4) getall and setall

17.12. functions/is_text, myascii,
unistr, str2uni,
utf2uni, con2uni [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

bret = is_text(input_str)
atxt = myascii(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.
since version 2.1.5 (2020/08/24), 'ascii' replaced with 'myascii'
since version 2.2.0 (2021/05/27) myascii tries several codecs

17.13. functions/is_wq [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

bret = is_wq(attr, lang=NONE)

ARGUMENT

unicode or byte string attr: attribute str lang: kernel lang (default NONE)

RESULT

bool bret: true if att in T, C0 .. C9, $0 .. $9, $A .. $Z

HISTORY

introduced 14.03.2020 - 2.1.1
added water hardness (TH / HD / DU 24.11.2021 - 2.2.7)

17.14. 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'

17.15. 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.

17.16. functions/piccolo_context [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

PURPOSE

Reads Context.pic and return colorset and tresholds for given attribute

SYNTAX

attr, cname, tvals, cvals = piccolo_context(fcontext, attr=NONE, verbose=False)

ARGUMENT

str fcontext: name of context file
str attr: attribute to find colorset and thresholds
bool verbose: for printing lookup messages

RESULT

str attr: attribute found
str cname: name of colorset
list tvals: str list of values / float list of thresholds
list cvals: str list of colors

REMARK

Returns as many colors as str thresholds if attr is alphanumeric; one more color than float thresholds if attr is numeric.

A tuple of NONE is returned in case of failure

HISTORY

introduced 2.2.6 (211117)

17.17. functions/quotefilename [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

txt = quotefilename(name)

ARGUMENT

str name: file name

RESULT

string txt: file name quoted with double quotes if it contains a whitespace.

HISTORY

added 11/09/2015.

17.18. 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)) HISTORY: * 20.03.13 (2.1.1) fixed rounding when val < 1

17.19. 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.

17.20. functions/update_package [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

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

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)
2.0.0 (180818) added verbose parameter
2.0.5 (190109) remove testing access
2.0.7 (190821) modified python exe lookup for venv Compatibility
2.0.9 (200205) minor fix in version_as_tuple: remove 4th level (post)
2.1.5 (210929) exit in embed mode if version inappopriate
2.2.9 (220214) replace -only-binary with -prefer-binary; add --trusted-host pypi.org

17.21. functions/utf8_bom_encoding [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

encoding = utf8_bom_encoding(filename=NONE)

ARGUMENT

string filename: input file name (defaults to NONE)

RESULT

string encoding:

    * 'utf_8_sig' if no file argument passed
    * 'utf_8_sig' if file exists and encoding is utf8-bom
    * NONE if file does not exists or encoding is not utf8-bom

HISTORY

210310 (2.1.7): creation
210423 (2.1.9): fix empty file resulting in StopIteration exception

17.22. functions/winstr, utf,
ws, aws,
codewinfile [ Fonctions ]

[ Top ] [ functions ] [ Fonctions ]

SYNTAX

out_txt = winstr(input_str)
out_txt = utf(input_str)
out_str = ws(input_str)
out_astr = aws(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
out_astr: (unicode) string in python3, ascii unicode string in python2

REMARK

codewinfile and winstr are synonyms

HISTORY

ws has been introduced 30.05.2018 - 1.9.3
aws has been introduced 12.06.2018 - 1.9.5

17.23. 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

18. ganessa.util/iterators [ Introduction ]

[ Top ] [ Introduction ]

18.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
2.0.0 (180816): python 3.7 Compatibility

TABLE OF CONTENTS

1. ganessa.multithread/Functions_mt [ Introduction ]

1.1. Functions_mt/mp_run [ Fonctions ]

1.2. Functions_mt/required_cpu [ Fonctions ]

2. ganessa.parallel/About [ Introduction ]

3. ganessa.parallel/Classes_mt [ Introduction ]

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

4. ganessa.plot/functions_plot [ Introduction ]

4.1. functions_plot/layout [ Fonctions ]

4.2. functions_plot/plotmes, plotmesx,pageplot, pageplotx [ Fonctions ]

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

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

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

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

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

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

8.2. Constants/DICT [ Constants ]

8.3. Constants/M, NONE [ Constants ]

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

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

9.2. Functions/areas [ Fonctions ]

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

9.4. Functions/commit [ Fonctions ]

9.5. Functions/cwfold [ Fonctions ]

9.6. Functions/dist2link [ Fonctions ]

9.7. Functions/dll_version, full_version [ Fonctions ]

9.8. Functions/extrnodes [ Fonctions ]

9.9. Functions/gencmd, gencmdw,raw_gencmdw, _gencmdw [ Fonctions ]

9.10. Functions/getall [ Fonctions ]

9.11. Functions/getcodescount, nextcode [ Fonctions ]

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

9.13. Functions/getid [ Fonctions ]

9.14. Functions/getindex, exists [ Fonctions ]

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

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

9.17. Functions/importEpanet, exportEpanet [ Fonctions ]

9.18. Functions/init [ Fonctions ]

9.19. Functions/is_embedded [ Fonctions ]

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

9.21. Functions/linkbbox [ Fonctions ]

9.22. Functions/linkXYZV, branchXYZV [ Fonctions ]

9.23. Functions/loadbin [ Fonctions ]

9.24. Functions/loadres [ Fonctions ]

9.25. Functions/nbobjects [ Fonctions ]

9.26. Functions/nbvertices [ Fonctions ]

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

9.28. Functions/nodeXYZ [ Fonctions ]

9.29. Functions/quit, close [ Fonctions ]

9.30. Functions/reset [ Fonctions ]

9.31. Functions/resfile, res_filename,model_filename [ Fonctions ]

9.32. Functions/save, savemodel [ Fonctions ]

9.33. Functions/selectlen, select [ Fonctions ]

9.34. Functions/setbatchmode [ Fonctions ]

9.35. Functions/setlang [ Fonctions ]

9.36. Functions/setlinkattr, setbranchattr,setnodeattr [ Fonctions ]

9.37. Functions/shearstr [ Fonctions ]

9.38. Functions/useExceptions, GanessaError,SimulationError, IsolatedNodeSimulationError [ Fonctions ]

9.39. Functions/wqtracevectsize [ Fonctions ]

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

10.1. Iterators/Branches, Links [ Iterator ]

10.2. Iterators/DemandCodes [ Iterator ]

10.3. Iterators/Demands [ Iterator ]

10.4. Iterators/Elements [ Iterator ]

10.5. Iterators/Nodes [ Iterator ]

10.6. Iterators/Selected [ Iterator ]

10.7. Iterators/Table [ Iterator ]

10.8. Iterators/Tanks, Reservoirs [ Iterator ]

10.9. Iterators/Unstable [ Iterator ]

10.10. Iterators/WQSources [ Iterator ]

11. ganessa.sim/sFunctions [ Introduction ]

11.1. sFunctions/browseH, browseWQ [ Fonctions ]

11.2. sFunctions/defcalind, getcalind [ Fonctions ]

11.3. sFunctions/full_solveH [ Fonctions ]

11.4. sFunctions/getallminmax [ Fonctions ]

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

11.6. sFunctions/inv_summary [ Fonctions ]

11.7. sFunctions/msmooth [ Fonctions ]

11.8. sFunctions/setWQresultfile [ Fonctions ]

11.9. sFunctions/solveH [ Fonctions ]

11.10. sFunctions/stat_quantiles, stat_duration [ Fonctions ]

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

4.2. functions_plot/plotmes, plotmesx,
pageplot, pageplotx [ Fonctions ]

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

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

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

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

9.9. Functions/gencmd, gencmdw,
raw_gencmdw, _gencmdw [ Fonctions ]

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

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

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

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

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

9.31. Functions/resfile, res_filename,
model_filename [ Fonctions ]

9.36. Functions/setlinkattr, setbranchattr,
setnodeattr [ Fonctions ]

9.38. Functions/useExceptions, GanessaError,
SimulationError, IsolatedNodeSimulationError [ Fonctions ]

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

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

17.3. functions/dist_to_poly, dist_p_seg,
dist, split_poly_at [ Fonctions ]

17.6. functions/formatting: strf2, strf3,
strf2loc, strf3loc,
stri, hhmmss,
strd [ Fonctions ]

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

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

17.11. functions/IniFile1L, get,
set, remove,
save [ Fonctions ]

17.12. functions/is_text, myascii,
unistr, str2uni,
utf2uni, con2uni [ Fonctions ]

17.22. functions/winstr, utf,
ws, aws,
codewinfile [ Fonctions ]