Runtime API feedback in 23.2

[DaveInCaz]

Recently we updated to EnergyPlus 23.2 which we are using through the Runtime API (not calling energyplus.exe directly from the command line). Previously we were using 9.5.

Below I've listed some observations / feedback about the API just based on the experience of making that upgrade. Some of these were 'pain points' when making the update, others are just notes about how to tweak the API, mostly in minor ways.

Note that my client program is written in C# and calls EnergyPlus using [DLLImport] facilitites.

I've consolidated this into one issue for the moment, but if it is useful/actionable feedback and you'd like me to create separate issues I can certainly do so. And/or add any other information if needed.

Thanks!

---

Details:

• EnergyPlus, Version 23.2.0-7636e6b3e9
• Operating system: Windows 10

---

1. Function energyplus(...) seems to have changed requirements for contents of argv

(Referring to int energyplus(EnergyPlusState state, int argc, const char *argv[]))

As of 23.2 the first entry of argv now gets removed (diff of CLI code...) which apparently was not the case before. So a dummy argument has to be provided there or else it will always return error code 1. It doesn't seem to matter what actual value is used for argv[0]; an empty string "" works fine for example. (Didn't try a null string).

(I didn't see any other way to get it to run successfully without that first 'dummy' argument, could I have missed something?)

---

2. Runtime API documentation could be clarified and may have some C++ / Python inconsistencies

(Note - I'm not sure who maintains this documentation... should feedback be directed elsewhere?)

Before realizing about args[0] and trying to debug why 23.2 was failing I compared its documentation to 9.5, i.e.,

• https://bigladdersoftware.com/epx/docs/9-5/input-output-reference/api-usage.html#subsec:runtime-api
  to
• https://bigladdersoftware.com/epx/docs/23-2/input-output-reference/api-usage.html#subsec:runtime-api

but there are no changes at all in the runtime API section.

In the docs, the C/C++ example only shows a case where the argc/argv from main() are directly passed to energyplus(). So in that case, argv[0] would indeed be the program's filename and should work fine. But this was not at all obvious when using the API and as mentioned wasn't required in 9.5; I recommend updating the documentation to make the argument requirements more explicit.

But the python example treats this differently, it says:

Note that when calling EnergyPlus as a library, you should just pass the arguments, not the filename itself. In Python, the argv variable will have the filename as the first item in the list, so this example trims that off.

This may be incorrect now? I have not tried it from Python.

---

3. Passing argc=0, argv=empty results in an access violation exception.

Seems like this case should be checked / handled without a crash.

I'm calling from C# so actually I'm providing a zero-length non-null string array, not sure precisely how that ends up represented in C++. The C# / .NET exception is a System.AccessViolationException with description

"Attempted to read or write protected memory. This is often an indication that other memory is corrupt."

The C# code is:

var energyplusState = StateNew();
var args = new List<string>(); // initialized but with no contents
...
var result = EnergyPlus(energyplusState, args.Count, args.ToArray());

---

4. Some of the preliminary text output does not utilize the callbacks

Specifically, referring to registerStdOutCallback and registerErrorCallback.

Example: calling energyplus(state, args.Count, args.ToArray()) where args contains:

args[0] = ""
args[1] = "--fake"

the callbacks are not called. But if you do the same thing on the command line there is some text which is produced:

C:\...\EnergyPlus-23.2.0-7636e6b3e9-Windows-x86_64>energyplus.exe --fake
The following argument was not expected: --fake
Run with --help for more information.

This text is apparently not provided to the callbacks.

It would be useful if all stderr / stdout output were consolidated to use the callbacks, as this would make debugging arguments easier from the API.

---

5. The --debug-cli option causes a process exit, even when used from the API

I noticed this option here:

EnergyPlus/src/EnergyPlus/CommandLineInterface.cc

Line 212 in 321d7d1

app.add_flag("--debug-cli", debugCLI, "Print the result of the CLI assignments to the console and exit")->group(""); // Empty group to hide it

Obviously this is intentionally hidden/undocumented, but figured I would mention this anwyay. If that option is used, function debugCLI() is called which ultimately calls exit(0):

EnergyPlus/src/EnergyPlus/CommandLineInterface.cc

Line 275 in 321d7d1

exit(0);

.

This is unlike other exit pathways which follow this pattern:

if (eplusRunningViaAPI) {
    return static_cast<int>(ReturnCodes::SuccessButHelper);
} else {
    exit(return_code);
}

such as:

https://github.com/NREL/EnergyPlus/blob/321d7d1e31bf2c316d7108d230260b13404d4a44/src/EnergyPlus/CommandLineInterface.cc#L226C1-L230C14

The call to exit(0) terminates whatever client program is calling the EnergyPlus API, quite unexpected.

---