Package: contamxpy
Python Bindings for ContamXcontamx-lib.libprovides an API wrapper around the simulation engine ofCONTAM, referred to asContamX.contamx-libenables control of CONTAM simulations, or co-simulation, via a C-language API. This Python package,contamxpy, provides another layer of access, i.e., Python bindings, tocontamx-lib.Driver Modulesare provided that demonstrate the use ofcontamxpy.py. These drivers importcontamxpy, obtain astateassociated with a specific CONTAM PRJ file, get properties of the simulation from thestate, and runs the simulation.NOTEcontamx-liballows for co-simulation to be performed according to the following:steady airflow with no contaminantssteady airflow with steady or transient contaminantstransient airflow with transient contaminantsOnly the Default Solver (Implicit Euler) is allowed for contaminant calculationsCo-simulation is not allowed for the following:Airflow simulations: Duct Balance, Building Airflow Test, or Building Pressurization TestContaminant simulations: Cyclic, Short Time Step, or CVODECFD analysisUsageTypically, one would work within a Python virtual environment which can be created and activated using the following commands.$ python -m venv .venv
$ .venv\Scripts\activate  (on Windows)Installcontamxpyfrom PyPI.$(.venv) python -m pip install contamxpyGet help for the test module from the command line.test_cxcffi.py -h

Usage: test_cxcffi.py [options] arg1  
    arg1=PRJ filename

Options:
  -h, --help    show this help message and exit
  -v VERBOSE, --verbose=VERBOSE
                define verbose output level: 0=Min, 1=Medium,
                2=MaxDriver ModulesDemonstration cases are provided with the downloadable source distribution. Example drivers and test cases, i.e., CONTAM PRJ and associated input files (WTH, CTM), will be in thedemo_filesfolder. This example command line runs thetest_OneZoneWthCtm.pymodule withtest_GetPrjInfo.prjusing the--verbose=2command line option and redirects it to a text file namedout.txt. Reviewout.txtfor detailed information obtained from the PRJ file via thecontamxpymodule.test_OneZoneWthCtm.py test_GetPrjInfo.prj --verbose=2 > out.txtSome driver modules (listed below) are case-specific and provide boundary conditions (WTH and CTM-like) for their respective PRJ files. See detailed information on each driver program in the documentation.test_OneZoneWthCtm.pytest_OneZoneWthCtm-UseApi.prjtest_OneZoneWthCtmStack-UseApi.prjvalThreeZonesWthCtm-UseApi.prjtestGetPrjInfo.prjtest_cxcffi.pytest_OneZoneWthCtm.prjtest_OneZoneWthCtmStack.prjvalThreeZonesWthCtm.prjtest_OneFloorWpcAddMf.pytest_OneFloorWpcAddMf-UseApi.prjtest_OneZoneSS.pytest_OneZoneSS-UseApi.prjtest_OneZoneSsStack-UseApi.prjtest_OneZoneSS-Loop.pytest_OneZoneSsStack-UseApi.prjcontamxpyis thread safe, and thetest_Multirun.pydriver demonstrates this capability by running multiple PRJ files provided in a list file using the Pythonthreadingmodule.NOTE: At the time of this release,contamxpycannot be used with Python's multiprocessing capabilities due to pickling limitation of CFFI-based modules.test_MultiRun.py (Use --help option for details)prjFile.lstreg_solverContTrace-mz-MH-trans-3day.prj, test_GetPrjInfo.prj, test_OneFloorWpcAddMfYear.prj, test_OneZoneWthCtmStackYear.prj, test_OneZoneWthCtmYear.prj, valThreeZonesWthCtmYear.prjDocumentationThedocsfolder in the source distribution file (e.g.,contamxpy-#.#.#.zip) contains a PDF with detailed documentation of the API and the accompanying demonstration cases.NIST Developer NotesThese bindings were developed using theC Foreign Function Interface (CFFI). CFFI utilizes C header files that define thecontamx-libAPI.contamx-lib.libis a statically linked build of ContamX with an API, i.e.,contamx-lib. A dynamic Python module (.pyd) is built that incorporates the static build.NOTE:The Windows version of the static build ofcontamx-lib.libmust include the following dependencies:WSock32.lib,WS2_32.lib, anduser32.lib. On linux, the static build ofcontamx-libmust be namedlibcontamx-lib.afor wrapping intocontamxpy.Steps to Develop Python Bindings1. Create directory forcontamxpyEither clone the repo (NIST developers only) ORDownload the source distribution fromhttps://pypi.org/project/contamxpy/Source files:contamxpy\  
|
| setup.py
| setup.cfg
| MANIFEST.in 
| LICENSE.txt
| README.md
| contamxpy_build.py
| contamxpy.py
| contamx-lib.lib
|
├── include\
|   └── contam-x-cosim.h
|       string-len-max.h
|       types.h
|
└── demo_files\
    └── cxResults.py
        cxRunSim.py
        test_cxcffi.py
          test_OneZoneWthCtm.prj/.wth/.ctm
          test_OneZoneWthCtmStack.prj/.wth/.ctm
          valThreeZonesWth.prj/.wth/.ctm
          test_OneFloorWpcAddMf.prj
          test_OneFloor.wpc
        test_OneZoneWthCtm.py
          test_OneZoneWthCtm-UseApi.prj
          test_OneZoneWthCtmStack-UseApi.prj
          test_GetPrjInfo.prj
        test_OneFloorWpcAddMf.py
          test_OneFloorWpcAddMf-UseApi.prj
        test_MultiRun.py
          prjFile.lst
          reg_solverContTrace-mz-MH-trans-3day.prj
          MD-Balt-EPW.wth
          test_OneFloorWpcAddMfYear.prj 
          test_OneFloorYear.wpc
          test_OneZoneWthCtmStackYear.prj/.wth/.ctm
          test_OneZoneWthCtmYear.prj/.wth/.ctm
          valThreeZonesWthCtmYear.prj/.wth/.ctm
        test_OneZoneSS.py
          test_OneZoneSS-UseApi.prj
          test_OneZoneSS.prj
          test_OneZoneSS-Transient.prj/.wth/.ctm
        test_OneZoneSS-Loop.py
          test_OneZoneSsStack-UseApi.prj2. Create virtual environmentpython -m venv .venv3. Activate virtual environmentWindows =>.venv\Scripts\activate.bat4. Install required packages:$ python -m pip install cffi, wheel, numpycffiandwheelare required for developmentcffiandnumpyare required to run example driver modules5. GeneratecontamxpyRun the build module.contamxpy_build.pyThis should generate_contamxpy.c, etc.contamxpy\  
|
├── Release\
|   └── ... *.exp/.lib/.obj
|
└── _contamxpy.c
    _contamxpy.cp310-win_amd64.pydMost importantly it will generate a dynamic python module, e.g.,_contamxpy-cp310-win_amd64.pydthat provides a wrapper tocontamx-lib.lib.6. Install the development version locally$(.venv) pip install .Alternatively,contamxpycan be installed from the wheel file after the next step is completed by replacing "." in the above command by the path to the filename of the wheel file that is generated.7. Generate Files for DistributionBuilt distribution, i.e., wheel file:$(.venv) python -m setup bdist_wheelSource distribution, i.e., compressed archive (.zip, .gz):$(.venv) python -m setup sdist --format=zip
AND/OR
$(.venv) python -m setup sdistDevelopment Filescxcffi_build.pyThis module is used to produce the dynamic python module using CFFI to wrap the static library,contamx-lib.from__future__importannotations# Using the "out-of-line", "API mode"fromcffiimportFFICDEF='''\// NOT SHOWN: typedef and function prototypes for contamx-lib.lib'''SRC='''\#include "include//contam-x-cosim.h"'''ffibuilder=FFI()ffibuilder.cdef(CDEF)ffibuilder.set_source("_contamxpy",SRC,include_dirs=['.','include'],# C header files for contam-x-liblibraries=['contamx-lib'],# Library to link with (.lib, .dll))if__name__=="__main__":ffibuilder.compile(verbose=True)contamxpycontamxpyimplements thecxLibclass that provides the wrapper tocontamx-lib. This module is imported for use by driver programs listed above.NOTE: Code not shown here.setup.pyfromsetuptoolsimportsetupsetup(cffi_modules=['contamxpy_build.py:ffibuilder'])setup.cfg[metadata]name=contamxpyversion=0.0.8description=Python wrapper for the CONTAM Simulation Engine, ContamXlong_description=file: README.mdlong_description_content_type=text/markdownauthor=W. Stuart Dols, Brian Polidoro, NISTauthor_email=william.dols@nist.govlicense=Public Domainlicense_files=LICENSE.txtclassifiers=License:: Public DomainLicense:: OSI Approved :: BSD LicenseProgramming Language:: Python :: 3Programming Language:: Python :: 3 :: OnlyProgramming Language:: Python :: Implementation :: CPythonProgramming Language:: Python :: Implementation :: PyPyTopic:: Scientific/Engineeringproject_urls=Web Page=https://www.nist.gov/el/energy-and-environment-division-73200/nist-multizone-modeling/Source=https://pypi.org/project/contamxpy/[options]py_modules=contamxpypython_requires=>=3.7install_requires=cffi>=1setup_requires=cffi>=1[bdist_wheel]py-limited-api=cp37MANIFEST.inThe manifest file is used to add files to the source builds.include contamx-lib.*
include libcontamx-lib.*
include contamxpy_build.py
include include/*.h
include demo_files/*.py
include demo_files/*.prj
include demo_files/*.wth
include demo_files/*.ctm
include docs/Makefile
include docs/make.bat
include docs/source/*.rst
include docs/source/conf.py
include docs/build/latex/contamxpy.pdfREFERENCEShttps://www.youtube.com/watch?v=X5irxO5VCHwhttps://github.com/asottile/ukkonenhttps://cffi.readthedocs.io/en/latest/index.htmlhttps://docs.python.org/3.10/distutils/index.htmlhttps://setuptools.pypa.io/en/latest/setuptools.htmlhttps://packaging.python.org/en/latest/tutorials/packaging-projects/TODOProvide static build oflibcontamx-lib.afor Linux.