Question regarding co-simulation

[Xingji Yu]

Hi, 

I have a question regarding the co-simulation for Contam. I saw most people use Contam 3D exporter to create the .fmu file for the co-simulation. I saw most people use EnergyPlus as the master to control the co-simulation. I am wondering if it is possible to load the .fmu file in Python and Python perform the master to control the co-simulation. I saw some examples of co-simulation between EP and Python, the Python load the .fmu file and use model.get and model.set to exchange the data for co-simulation. I am wondering the ContamFMU can be used in the same way. Or the co-simulation can be only used that EP performs as the master?

Best,

Xingji

[Stuart Dols]

I can't really tell from your message what it is you are trying to accomplish with CONTAM. However, I can direct you to the recently developed python bindings for ContamX. You can find contamxpy available on PyPI. While contamxpy is in the developmental stages, it is a fully functional wrapper around a pre-release version of ContamX 3.4.1.7. Documentation of the API, several example python driver programs, and accompanying CONTAM PRJ files are available with the source package via PyPI.

https://pypi.org/project/contamxpy/

Check it out to see if it will meet your needs.

- Stuart

--
To unsubscribe from this group, send email to contam+un...@list.nist.gov
 
View this message at https://list.nist.gov/contam
---
To unsubscribe from this group and stop receiving emails from it, send an email to contam+un...@list.nist.gov.

[Xingji Yu]

Hi Stuart,

Thanks for your reply. Since I am new user of Contam I still have some questions regarding using Contam for co-simulation.

What I want to do is basically use Contam co-simulation to do the ventilation simulation and take the needed results back to Python for the ventilation part and then use Python to co-simulate with EnergyPlus for the thermal domain simulation and probably other domains in the future.

I have checked the page of contampy. It seems that contampy can operate directly the ContamX to execute the .PRJ file to do the ventilation simulation without using the Contam 3D exporter to create the .fmu file. Do I misunderstand this part? If contampy can directly operate the .PRJ file, then it is not necessary to use the Contam 3D exporter to create the .fmu file anymore for the co-simulation. Is this correct? Please correct me if my understanding is wrong. Thank you very much.

Best,

Xingji

[Dols, William Stuart (Fed)]

Xingji,

contamxpy has nothing inherently to do with FMI or EnergyPlus. It provides a wrapper around the CONTAM simulation engine, ContamX, that can be imported into python modules. It provides the ability to control simulation execution, obtain simulation results, and exchange data with ContamX using a very similar API as provided by ContamX’s socket communication API. Note that contamxpy is a wrapper around a statically linked, contamx-lib. However, contamx-lib is also available as a DLL which provides a C interface/API.

The ContamFMU.dll requires another program to provide the controlling, i.e., master, algorithm, e.g., EnergyPlus, as per the FMI for Co-Simulation specification version 1.0. It was written specifically to work with EnergyPlus, although there is nothing inherent to prevent one from utilizing it with another controlling program. While it is convenient, one need not use the Contam3DExporter to generate an FMU (which is simply a zip archive which also conforms to FMI specifications). The FMU generated by 3DExporter does contain the PRJ which is used to generate the associated EnergyPlus IDF file. ContamFMU.dll acts as a means to exchange variables between EnergyPlus and ContamX at each simulation time step during co-simulation.

I have not attempted to utilize ContamFMU in conjunction with other FMUs either with or without EnergyPlus providing the controlling algorithm.

You say you want to use EnergyPlus, but you do not want to use it to provide the controlling algorithm.
From your messages, the reasons for this are not apparent to me (that’s not to say that there couldn’t be any good ones 😊).

- Stuart

[Xingji Yu]

Thank you so much for the answer.

[Dols, William Stuart (Fed)]

Just as the building check pointed out, there is an undefined Simple AHS in the PRJ.
If you click on the message in the building check dialog, it will take you to the offending item.

 

 

- Stuart

 

From: Xingji Yu <yuxing...@gmail.com>
Sent: Friday, December 1, 2023 12:19 PM
To: CONTAM <con...@list.nist.gov>
Cc: Dols, William Stuart (Fed) <willia...@nist.gov>; Stuart Dols <stu...@gmail.com>; CONTAM <con...@list.nist.gov>; Xingji Yu <yuxing...@gmail.com>
Subject: Re: [contam] Question regarding co-simulation

 

Hi Stuart,

 

I have one more question. I am now setting up the Contam model AHU unit. I tried to run the simulation, but it reports an error saying: undefined smple AHS. I think I followed the tutorial online, but the error did not happen in the tutorial. Could you tell what could be the reason for this error? I put my .prj file in this message.

 

Best,

Xingji

On Tuesday, October 31, 2023 at 8:50:40 PM UTC+1 Dols, William Stuart (Fed) wrote:

[Xingji Yu]

Hi Stuart,

Thanks for the answer; now I noticed that there is an AHU icon put on top by mistake. 

Xingji

[Xingji Yu]

Hi Stuart,

Sorry for bothering you again. I am checking the demo_files folder of contampy and tried to run them, and it works. Basically, python can control the simulation execution, obtain simulation results, and exchange data with ContamX from the examples. I think it is realized by the control blocks (in green) in contam,  but I cannot find the blocks in the software, is there any tutorials that systematically introduce the routine to set those blocks?

Further, you asked why I want to use EnergyPlus, but you do not want to use it to provide the controlling algorithm. The reason is that the current ongoing project may not just involve contam and energyplus in the co-simulation routine. Some other daylighting simulations from other tools may also be involved later, and final target framework may be in real time. Thus, it is better to use Python as the master to manage the whole workflow. This also gives some flexibility for future extension script to be integrated if some optimal control algorithm is going to be added.

I plan to just use contam for the ventilation system simulation and get information about the ventilation heat gain and maybe contaminants, and then send those values to python, Python will take the ventilation heat gain and send to EnergyPlus (by FMU approach). Then the next time step starts. Do you think it sounds technically feasible for current contam and comtampy to do that?

Best,

Xingji

On Tuesday, October 31, 2023 at 8:50:40 PM UTC+1 Dols, William Stuart (Fed) wrote:

[Dols, William Stuart (Fed)]

Please review the python driver programs and API documentation to help understand how to use the python bindings for the API.

The controls that you are showing have nothing to do with the API.
Only Constant (Set) and Split (pass) controls with Names assigned to them are accessible via the API.

The following shows the output when running test_cxcffi.py with the --verbose=1 option.

This shows the controls that are available to the API along with other building components found in the PRJ.

 

None of the example drivers demonstrate the use of the controls.

For this, you should refer to the following API functions:

 

I’m not sure about the “technical feasibility” of your simulation plan.

I will say to start out simple before trying to develop a complex building model.

 

- Stuart

 

From: con...@list.nist.gov con...@list.nist.gov On Behalf Of Xingji Yu
Sent: Wednesday, December 6, 2023 2:48 PM
To: CONTAM <con...@list.nist.gov>
Cc: Dols, William Stuart (Fed) <willia...@nist.gov>; Stuart Dols <stu...@gmail.com>; CONTAM <con...@list.nist.gov>; Xingji Yu <yuxing...@gmail.com>
Subject: Re: [contam] Question regarding co-simulation

 

Hi Stuart,

 

Sorry for bothering you again. I am checking the demo_files folder of contampy and tried to run them, and it works. Basically, python can control the simulation execution, obtain simulation results, and exchange data with ContamX from the examples. I think it is realized by the control blocks (in green) in contam,  but I cannot find the blocks in the software, is there any tutorials that systematically introduce the routine to set those blocks?

[Xingji Yu]

Hi Stuart,

Thanks a lot for the answer. 

I misunderstood how the co-simulation worked. I first thought the input and output of the data exchange were accomplished by the control icon and contampy. Now I know the data exchange is directly done by the API. Thanks for the correction.

However, I am still interested in how the control icon works. I checked the help document, and there is a control chapter. I tried to follow the instructions to create the control icon like below. It seems that I cannot change the area of Element Defined and Super Node Reference. After I click ok, the green control icon does not pop up, it seems the logic of setting super elements are very different.

Best,

Xingji

[William Dols]

Super Elements require their own controls network to be drawn on the "Super Element" SketchPad.

Check out the example PRJ provided in a previous post.

https://groups.google.com/a/list.nist.gov/g/contam/c/3Q63EoW4VyY/m/JkXX-XQ5AgAJ

However, before diving into Super Elements, one should become familiar with controls in general.

- Stuart

[Xingji Yu]

Hi Stuart,

Regarding the comments ''This shows the controls that are available to the API along with other building components found in the PRJ.'. I checked the corresponding .prj file. It seems the other building components that you mentioned are actually the ''super elements'. It seems that the control value is sent to the super element ''Control(3)' and then the set zone temperature action can be done through the contamxpy. So the green super element is actually necessary for the co-simulation (for parsing the values), is that right?

Best,

Xingji

[William Dols]

Xingji,

The "other building components" I mentioned are the contaminants, zones, paths, AHSs, junctions, terminals, and leaks.
The image that you sent contains no "super elements/nodes", only what appear to be other types of controls - perhaps Set and Pass types.
Controls are not required to use the setZoneTemperature() API function of contamxpy.
You can search the documentation (contamxpy.pdf) for the setZoneTemperature function to see that it is demonstrated in the demo_OneZoneWthCtm.py example.
NOTE: Look at the cxLib class in the documentation for the "set..." and "get..." functions which make up significant functionality of the API.

Controls are not "necessary" to perform co-simulation. They are an optional method to exchange data during co-simulation for information that is not provided via the other API function calls.

Only Constant (Set, indicated as "CT_SET" in my previously highlighted content) and Split (Pass, "CT_PASS" as previously highlighted) controls can be used to exchange info via controls during co-simulation.

- Stuart

[Xingji Yu]

Hi Stuart,

I hope you’re doing well. I’ve been working with Contam and the contamxpy Python interface, and I’m trying to dynamically modify mechanical ventilation flow rates in my simulation. However, I’m a bit confused about how Simple Air Handling Systems (AHS) are represented—particularly in cases where there is no visible AHS icon in the demo .prj file’s geometry (like test_OneZoneWthCtm.prj).

I’ve looked at the sample project test_OneZoneWthCtm.prj, which (from the geometry) appears to have no explicit mechanical ventilation components or icons, yet the Python script uses functions like setAhsSupplyReturnFlow(path_num, flow). This makes me wonder whether the project has a “hidden” or implicit AHS definition that isn’t visible in the SketchPad.

In my own .prj files, whenever I define an AHS, I see an icon on the SketchPad. Is it possible to configure an AHS without any icon showing up, as the example seems to do? If so, could you clarify how the AHS is defined behind the scenes? Or is there another recommended way to handle mechanical ventilation so that I can directly call setAhsSupplyReturnFlow (or any other relevant function) in contamxpy to adjust the flow rates?

Essentially, my questions are:

Can I dynamically modify mechanical ventilation flow rates purely through contamxpy (e.g., using setAhsSupplyReturnFlow), without having to rely on a visible mechanical ventilation icon in the .prj geometry?
If the example .prj doesn’t show an AHS icon, where is it actually defined?
Are there any best practices for setting up an AHS or other mechanical ventilation in Contam so that I can reliably call these Python methods to control the flow?
Thank you in advance for your help and for all your work on Contam. Any guidance you can provide would be greatly appreciated!

Best,

Xingji

[Dols, William Stuart (Fed)]

Xingji,

You can add an AHS to the test_OneZoneWthCtm-UseApi.prj.

The associated script, test_OneZoneWthCtm.py, will then set the number of AHSs to 1 and set the flows and OA fraction as per the arrays of associated data (set via setWthCtmInit() and setWthCtmData() functions).

 

The attached PRJ does just this with a filter incorporated into the OA of the AHS to show the affects of the AHS on the indoor contaminant results.

 

There are no “hidden” AHSs in the test_OneZoneWthCtm-UseApi.prj, it is just that there are none detected within the PRJ, so the associated AHS functions are not called.

The properties of the PRJ (including number of AHSs) are determined upon instantiation of the cxLib object as shown in the highlighted line of code:

 

You can read about the cxLib class and associated construtor in the documentation, contamxpy.pdf.

- Stuart

 

From: Xingji Yu <yuxing...@gmail.com>
Sent: Friday, February 21, 2025 7:28 AM
To: CONTAM <con...@list.nist.gov>
Cc: Dols, William Stuart (Fed) <willia...@nist.gov>; yuxing...@gmail.com <yuxing...@gmail.com>; stu...@gmail.com <stu...@gmail.com>; CONTAM <con...@list.nist.gov>
Subject: Re: [contam] Question regarding co-simulation

 

Hi Stuart,

 

I hope you’re doing well. I’ve been working with Contam and the contamxpy Python interface, and I’m trying to dynamically modify mechanical ventilation flow rates in my simulation. However, I’m a bit confused about how Simple Air Handling Systems (AHS) are represented—particularly in cases where there is no visible AHS icon in the demo .prj file’s geometry (like test_OneZoneWthCtm.prj).

 

None of the example drivers demonstrate the use of the controls.

For this, you should refer to the following API functions:

 

I’m not sure about the “technical feasibility” of your simulation plan.

I will say to start out simple before trying to develop a complex building model.

 

- Stuart

 

From: con...@list.nist.gov con...@list.nist.gov On Behalf Of Xingji Yu
Sent: Wednesday, December 6, 2023 2:48 PM
To: CONTAM <con...@list.nist.gov>
Cc: Dols, William Stuart (Fed) <willia...@nist.gov>; Stuart Dols <stu...@gmail.com>; CONTAM <con...@list.nist.gov>; Xingji Yu <yuxing...@gmail.com>
Subject: Re: [contam] Question regarding co-simulation

 

Hi Stuart,

 

Sorry for bothering you again. I am checking the demo_files folder of contampy and tried to run them, and it works. Basically, python can control the simulation execution, obtain simulation results, and exchange data with ContamX from the examples. I think it is realized by the control blocks (in green) in contam,  but I cannot find the blocks in the software, is there any tutorials that systematically introduce the routine to set those blocks?

[Xingji Yu]

Hi Stuart,

Thanks for your reply. I am currently testing a simplified Python script using contamxpy to verify if I can dynamically modify boundary conditions in Contam. In my test, I vary the mechanical ventilation flow rate (fan airflow) by adjusting it during different time steps (day vs. night). Although I see changes in infiltration when ambient temperature is varied, the infiltration flow (InfFlow) remains constant when I change the mechanical ventilation value.

My observation is that although I change the mechanical ventilation value (fan_airflow) dynamically (varying between day and night), the infiltration flow (InfFlow) remains unchanged when I fix the ambient temperature (amb_temp = 15.0). In contrast, when I vary the temperature, infiltration changes accordingly.

Could you please advise:

1. Is my method of calling mechanical ventilation (via setAhsSupplyReturnFlow) correct, or might there be an issue in the way I'm updating it?
2. Could this behavior be related to my .prj file settings (i.e., how the paths or flow resistances are defined) so that mechanical ventilation does not affect infiltration as expected?

I am attaching the Python code along with the .prj file for your review. I appreciate any guidance you can provide regarding this issue.

Best regards,

Xingji

[Dols, William Stuart (Fed)]

When I run your module, the resultant SIM file is invalid, i.e., I can’t view results via ContamW.
You should be able to verify whether your results are as desired by viewing the results with ContamW.
I don’t really have time to debug this.

I don’t see any reason why modifications to temperature should affect infiltration for this case as all flow paths are located at the same elevation. This means that there will be no buoyancy-driven airflow.

 

- Stuart

 

From: Xingji Yu <yuxing...@gmail.com>
Sent: Monday, February 24, 2025 11:31 PM
To: CONTAM <con...@list.nist.gov>
Cc: Dols, William Stuart (Fed) <willia...@nist.gov>; stu...@gmail.com <stu...@gmail.com>; CONTAM <con...@list.nist.gov>; Xingji Yu <yuxing...@gmail.com>
Subject: Re: [contam] Question regarding co-simulation

 

Hi Stuart,

 

Thanks for your reply. I am currently testing a simplified Python script using contamxpy to verify if I can dynamically modify boundary conditions in Contam. In my test, I vary the mechanical ventilation flow rate (fan airflow) by adjusting it during different time steps (day vs. night). Although I see changes in infiltration when ambient temperature is varied, the infiltration flow (InfFlow) remains constant when I change the mechanical ventilation value.

My observation is that although I change the mechanical ventilation value (fan_airflow) dynamically (varying between day and night), the infiltration flow (InfFlow) remains unchanged when I fix the ambient temperature (amb_temp = 15.0). In contrast, when I vary the temperature, infiltration changes accordingly.

Could you please advise:

1. Is my method of calling mechanical ventilation (via setAhsSupplyReturnFlow) correct, or might there be an issue in the way I'm updating it?
2. Could this behavior be related to my .prj file settings (i.e., how the paths or flow resistances are defined) so that mechanical ventilation does not affect infiltration as expected?

I am attaching the Python code along with the .prj file for your review. I appreciate any guidance you can provide regarding this issue.

Best regards,

Xingji

 

On Friday, February 21, 2025 at 4:40:28 PM UTC+1 Dols, William Stuart (Fed) wrote:

Xingji,

You can add an AHS to the test_OneZoneWthCtm-UseApi.prj.

The associated script, test_OneZoneWthCtm.py, will then set the number of AHSs to 1 and set the flows and OA fraction as per the arrays of associated data (set via setWthCtmInit() and setWthCtmData() functions).

 

The attached PRJ does just this with a filter incorporated into the OA of the AHS to show the affects of the AHS on the indoor contaminant results.

 

There are no “hidden” AHSs in the test_OneZoneWthCtm-UseApi.prj, it is just that there are none detected within the PRJ, so the associated AHS functions are not called.

The properties of the PRJ (including number of AHSs) are determined upon instantiation of the cxLib object as shown in the highlighted line of code:

 

You can read about the cxLib class and associated construtor in the documentation, contamxpy.pdf.

- Stuart

 

None of the example drivers demonstrate the use of the controls.

For this, you should refer to the following API functions:

 

I’m not sure about the “technical feasibility” of your simulation plan.

I will say to start out simple before trying to develop a complex building model.

 

- Stuart

 

From: con...@list.nist.gov con...@list.nist.gov On Behalf Of Xingji Yu
Sent: Wednesday, December 6, 2023 2:48 PM
To: CONTAM <con...@list.nist.gov>
Cc: Dols, William Stuart (Fed) <willia...@nist.gov>; Stuart Dols <stu...@gmail.com>; CONTAM <con...@list.nist.gov>; Xingji Yu <yuxing...@gmail.com>
Subject: Re: [contam] Question regarding co-simulation

 

Hi Stuart,

 

Sorry for bothering you again. I am checking the demo_files folder of contampy and tried to run them, and it works. Basically, python can control the simulation execution, obtain simulation results, and exchange data with ContamX from the examples. I think it is realized by the control blocks (in green) in contam,  but I cannot find the blocks in the software, is there any tutorials that systematically introduce the routine to set those blocks?

[David Lorenzetti]

Xingji,

I scanned over your Python script.  It looks to me like the reason you don't see infiltration changing when you change the `fan_airflow` variable is that you make the same change to both the supply and return paths in the ventilation system:

contam_model.setAhsSupplyReturnFlow(supplyPathNum, fan_airflow)

contam_model.setAhsSupplyReturnFlow(returnPathNum, fan_airflow)

That probably means you don't change the effect that the AHS has on the airflow balance in the zone (AHS pushes and pulls the same amount of air, so it doesn't affect the airflow balance that the other paths are working out together).

I didn't try to run the model, but you can check this suggestion by doing something like this:

contam_model.setAhsSupplyReturnFlow(supplyPathNum, fan_airflow)

contam_model.setAhsSupplyReturnFlow(returnPathNum, fan_airflow * 0.8)

-Dave

[Xingji Yu]

Hi Dave and Stuart,

I have recently changed the setup. but still integrating Contam via the Python contamxpy.cxLib API in a co-simulation with an EnergyPlus FMU. I’m having trouble getting dynamic infiltration to respond to the wind speed & direction that I feed in at each timestep. Below is a concise summary of what I’ve tried, what I observe, and where I’m stuck. I have attached the test file of python and .prj.

I’m seeing unexpected zero infiltration when I feed in dynamic wind conditions. A quick summary of my setup and questions:

1. Zero infiltration with dynamic wind
   – I’ve configured only three external wall leak paths (IDs 1–3). If I assign each a constant 100 Pa wind pressure in the GUI, I see non-zero airflow. But when I switch them to “Variable” wind pressure and drive Contam with a time series of wind speed & direction via Python

   
   

   contam_model.setAmbtWindSpeed(v)                                                                                                                                                                                                                                      contam_model.setAmbtWindDirection(dir)                                                                                                                                                                                                                                                      contam_model.doSimStep(1)

   the summed infiltration remains exactly zero. Shouldn’t the variable-pressure option internally compute Δp from v and apply it to each path?

2. Exposing or overriding per-path Δp
   – There’s no setAmbtWindPressure() in cxLib, so I can’t push per-path pressure differences from Python. Does Contam automatically calculate Δp = ½·ρ·v²·Cp(azimuth)? If so, is there a way to inspect those Cp or Δp values at runtime? Or must I pre-compute and feed in a constant wind pressure schedule?

3. Best practice for a sealed glazing wall
   – My south façade is a sealed triple-glazing unit (no supply-air mode). I’m using Leakage Area Data (per item) with reference Δp=10 Pa, C=0.6, n=0.65. Would “Orifice Area Data” or another model better represent a solid glazed wall’s leakage characteristics?

Any pointers on how to get non-zero, time-varying infiltration — or how to debug Contam’s internal Δp application — would be greatly appreciated.

Thanks for your help

Xingji

[William Dols]

This issue appears to have nothing to do with co-simulation.

One must first understand the basics of CONTAM.
Please review the Introduction to CONTAM Tutorials (specifically, Parts 2 and 3) for how to address wind pressure.
https://www.nist.gov/el/energy-and-environment-division-73200/nist-multizone-modeling/contam-video-tutorials

Setting all 3 paths to have a wind pressure of 100 Pa and the AHS supply and return to have the same flow rate should result in no infiltration, i.e., essentially zero flow through the envelope flow paths.

Your PRJ is currently configured such that each flow path uses the same, constant wind pressure coefficient profile of 1.0.
This will result in all three flow paths always having equal wind pressures.

You can also look to the demonstration cases provided with contamxpy.
The test_OneZoneWthCtm-UseApi.prj and its associated driver program (demo_OneZoneWthCtm.py) as well as the associated CONTAM-only PRJ (test_OneZoneWthCtm.prj) demonstrate how wind can vary based on wind pressure coefficient profiles and the contents of the WTH file.

- Stuart