Difference between Normal Functions and Bin Functions


Apologies for the (possibly stupid) question, I have only just started using the toolkit in MatLab…

Could someone please explain the difference between using a ‘normal’ function and a ‘bin’ function? For example, when adding a new junction, when would you choose to use ‘d.addNodeJunction()’ and when ‘d.addBinJunction()’ or how would you choose between ‘d.setNodeTankInitialLevel()’ and ‘setBinNodeTankInitialLevel()’?


Certainty not a stupid question :slight_smile:

“Normal” functions make direct calls to the EPANET library. So essentially you are bounded by the capabilities (and the limitations of the EPANET version you are using). Typically when you “set” something in EPANET, it stays in the memory, but it does not create a new .inp file.

“bin” functions are relying on a different way to execute EPANET. This does not involve calling the library, and the .inp file is not in the computer memory. Essentially, the epanet executable runs the Input file and it collects all the results in a binary file (hence the Bin name).

You may want to use Bin functions if you don’t want to call the library because it makes your code slower or because some functions haven’t yet been implemented in the EPANET library.

So, with d.setBinNodeTankInitialLevel(…) the toolkit will create a new input file with the new initial tank level and it will use that when executing bin functions. Perhaps you are running 10,000 Monte Carlo simulations, and you just want to avoid doing a step-by-step simulation for each time step.

With d.setNodeTankInitialLevel(…) the toolkit will change the entry in the memory where it stores the tank initial levels, without modifying the input file. Perhaps you are doing a few simulations where you make changes at various time steps.

Let me know if this helps. @Mariosmsk please correct me if I made a mistake :slight_smile:


1 Like

Thank you! That is very helpful :slight_smile:

Leading on from my last question… could you possibly provide a basic example/outline of how to use a Bin function to execute a command for which currently no function exists within EPANET library?

For instance I was wondering whether I could use a Bin function to change the NodeNameIDs of existing Nodes within the network, since there is no ‘setNodeNameID’ function in the library. Would this be possible?

The functions setNodeNameID and setBinNodeNameID do not exists. So, now you can use the functions for remove and add nodes. It would be good to add a new function to rename nodes / links.


I use the differential evolution algorithm to optimize the network pressure by the pressure relief valve and find the optimal points of the valves. The only problem I have is that the simulation is slow using normal functions. is it possible to guide how to use the Bin functions for this?

You can use the function d.getComputedTimeSeries (Computed Hydraulic & Quality Time Series using the binary file created from executable) with normal functions.

1 Like