BOPTestAPI.jl to hide REST API interactions

[bertrandkerres]

Hi,

not sure where this falls on the spectrum from "this could genuinely improve your work" to "please cite my paper", so feel free to close this if not needed :)

I have written a small Julia package called BOPTestAPI.jl that tries to hide the REST API interactions and data conversions from the user. So here's how an example script looks:

using BOPTestAPI
using DataFrames
using Plots

dt = 900.0 # time step in seconds
N = 10  # Number of time steps to take
testcase = "bestest_hydronic"

plant = initboptestservice!(BOPTEST_SERVICE_DEF_URL, testcase, dt)

# Get forecast data as well (for plotting later)
fc = getforecasts(plant, N * dt, dt)

# Run N time steps of baseline control
res = []
for t = 1:N
    u = Dict() # here you would put your own controller
    y = advance!(plant, u)
    push!(res, y)
end
dfres = DataFrame(res)
kpi = getkpi(plant)

stop!(plant)

df = leftjoin(dfres, fc, on = :time => :time)
pl1 = plot(
    df.time ./ 3600,
    Matrix(df[!, ["reaTRoo_y", "LowerSetp[1]"]]);
    xlabel="t [h]",
    ylabel="T [K]",
    labels=["actual" "target"],
)
pl2 = plot(
    df.time ./ 3600, df.reaQHea_y ./ 1000;
    xlabel="t [h]",
    ylabel="Qdot [kW]",
    labels="Heating"
)
plot(pl1, pl2; layout=(2, 1))

(this example runs a bit slow because it uses BOPTEST-Service from NREL directly).

The package hopefully works both with BOPTEST and BOPTEST-Service, it has MIT license and I put it in the Julia general registry (i.e. one can install it using the package manager, ] add BOPTestAPI). The docs are here: https://terion-io.github.io/BOPTestAPI.jl/stable/

If that is of interest, I could redo the example scripts in Julia to use this package instead.

[dhblum]

Hey @bertrandkerres! Real sorry for the delayed response here, but I appreciate your work and reporting here. Cool to see interest from the Julia community and a package to facilitate usage. A few thoughts:

• Regarding replacing our current Julia example with using your package, I think I would actually rather keep what we have. This is because I like how the example shows how a language other than Python can still interact with the native HTTP API of BOPTEST. That's kind of the purpose for keeping it around. And while use of your package would do that, I like that our example doesn't put anything "under-the-hood" with respect to the BOPTEST HTTP API.
• That said, I like making notice of your package for folks. What if we add reference to it on the README here as an additional interface/project like we do the Gym interface and BACnet interface?
• Regarding your comment "The package hopefully works both with BOPTEST and BOPTEST-Service", depending on your implementation and unless you explicitly know you've handled the small differences in the API correctly, it probably won't work for both BOPTEST-Service and for BOPTEST deployed locally with v0.6.0 and below. BUT, as of this PR, we've merged BOPTEST-Service as the only deployment architecture for BOPTEST, whether using locally or the web-service. That is to say, for the current master and for future releases from 0.7.0 (coming very soon) and onward, there won't be a difference in the API and your package should always work in all cases. This was a primary reason for the changes in the PR I reference, to streamline interface development and software maintenance generally.

Feel free to let me know any of your thoughts.

[dhblum]

FYI @javiarrobas about this discussion as someone who helps track usage as part of IBPSA Project 2.

[bertrandkerres]

Hi @dhblum, thanks for you response. I understand your point with keeping the "raw" HTTP request as an example somewhere, no problem for me :) I agree adding a reference in the README would be good then.

With respect to the differences between BOPTEST and BOPTEST-Service, the things it handles explicitly are:

• POST /select on BOPTEST-Service to select a test case at initialization, and store the received test-id
• Use endpoint base_url/service-name (e.g. localhost:5000/advance) for BOPTEST, and base_url/service-name/test-id for BOPTEST-Service

The user has to call initboptest!(base_url, ...) or initboptestservice!(base_url, testcase, ...) when creating a plant, but it should work automatically after that. At least in my admittedly limited testing it works for both, but I did not make a very thorough comparison between the APIs.

[dhblum]

Ok regarding the README. Will work on it.

And ah ok about the API, then yea they should work. But my comment still applies, the different handling won't be needed moving forward, you will only need to use the "BOPTEST-Service" version of the API.

[bertrandkerres]

👍

Thanks for the heads-up with the API changes. Once v0.7.0 is released, I will deprecate the parts that are no longer necessary.