Support for kPa is undocumented and not included in the toolkit API

[lbutler]

EPANET includes support for metric networks to provide results in both meters and kPa, however, this functionality is not documented either in OWA-EPANET or any official EPANET documentation I can find.

You can find the implementation of kPa within the codebase at these locations:

Reading PRESSURE in [OPTIONS] when reading an INP https://github.com/OpenWaterAnalytics/EPANET/blob/278037bab30960ad2623fb6f360e3f7900124ac2/src/input3.c#L1799-L1807

Setting kPa when initializing units https://github.com/OpenWaterAnalytics/EPANET/blob/278037bab30960ad2623fb6f360e3f7900124ac2/src/input1.c#L424-L425

Setting pressure conversion factor https://github.com/OpenWaterAnalytics/EPANET/blob/278037bab30960ad2623fb6f360e3f7900124ac2/src/input1.c#L443-L444

Including PRESSURE in [OPTIONS] when calling EN_saveinpfile https://github.com/OpenWaterAnalytics/EPANET/blob/8d8ccafad6d9864063362de5a79377dfc52f987a/src/inpfile.c#L638

This leads me to two questions:

1. Is support for kPa intended, even though it is undocumented?
2. Should we include APIs to allow toolkit users to access and set this option?

If the answers are yes to the above I propose that:

1. Documentation is updated to include this option
2. Functions are added to the toolkit to support setting and getting pressure units

My initial assumption is this will be two functions, EN_setpressureunits & EN_getpressureunits, and also exporting the enum PressureUnitsType

[LRossman]

An alternative to adding two new functions is to create a new analysis option (e.g. EN_PRESS_UNITS) used with the existing EN_setoption and EN_getoption functions.

The EN_setflowunits function resets the pressure units to meters whenever an SI flow unit is specified so I'm not sure how much of a problem this presents. I suppose it could check to see that if flow units remain as SI then no change is made to the pressure units.

Also what happens if the current flow units are US and EN_setpressureunits (or EN_setoption) changes pressure units to an SI measure. This will create a mix of unit systems in a model which would clash with the current convention. Perhaps any attempt to change pressure units that conflicts with the current unit system in place should simply not be allowed.

[lbutler]

@LRossman good suggestion on reusing the existing EN_setoption and EN_getoption functions, I would support this approach.

Apologies if I'm reading the function incorrectly but it looks like in EN_setflowunits the setting of Pressflag to meters is only if you were previously in US units https://github.com/OpenWaterAnalytics/EPANET/blob/278037bab30960ad2623fb6f360e3f7900124ac2/src/epanet.c#L1438-L1441

I haven't tested the code but I would assume if you were in KPA or METERS the else if would not apply.

It's a good question about the mixed units, currently in an INP if you attempt to set the pressure to kPa or meters while the flow units are in US, then the pressure option is ignored and PSI is set. So I can understand continuing with the current convention.

However, there are cases where certain regions will use mixed units. For example, I am in Canada and here all units are in metric except for pressure which is in PSI, which is used by both operational and engineering staff.

I have also been told in Mexico it's common for pipes to have nominal diameters in inches.

Personally, I can see the benefit to allow users to set any of the conversion factors manually, though it may be worth separating the discussion from this issue and sticking with convention now to simplify the task.