{"id":23940227,"url":"https://github.com/ecobee/building-controls-simulator","last_synced_at":"2025-04-12T12:32:26.580Z","repository":{"id":37204584,"uuid":"239921845","full_name":"ecobee/building-controls-simulator","owner":"ecobee","description":"Platform for running control loop co-simulations and generation of building  simulation models using EnergyPlus.","archived":false,"fork":false,"pushed_at":"2023-08-14T22:27:10.000Z","size":21892,"stargazers_count":16,"open_issues_count":25,"forks_count":10,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-26T07:11:13.254Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ecobee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2020-02-12T03:51:22.000Z","updated_at":"2025-01-27T05:56:51.000Z","dependencies_parsed_at":"2023-01-25T13:45:39.220Z","dependency_job_id":null,"html_url":"https://github.com/ecobee/building-controls-simulator","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecobee%2Fbuilding-controls-simulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecobee%2Fbuilding-controls-simulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecobee%2Fbuilding-controls-simulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecobee%2Fbuilding-controls-simulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecobee","download_url":"https://codeload.github.com/ecobee/building-controls-simulator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248566388,"owners_count":21125661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-06T03:13:00.108Z","updated_at":"2025-04-12T12:32:26.548Z","avatar_url":"https://github.com/ecobee.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Building Controls Simulator\n\nPackage for running control loop co-simulations and generation of building \nmodels using EnergyPlus.\n\nFor more information on EnergyPlus whole building simulation see [here](https://energyplus.net/).\n\n## Installation and Setup\n\nTo setup this repo open up your bash terminal and follow the commands below. \nIdeally use SSH for git access. If you haven't set that up you can use HTTPS.\n\n```bash\ngit clone\ncd building-controls-simulator\n```\n\n**Note for Windows users**: It is recommended that you clone the repository to a directory that is as short as possible and does not contain spaces or other special characters. For example, clone to `c:\\devel\\building-controls-simulator`.\n\n### Minimal Docker version\n\n```\n$ docker --version\nDocker version 19.03.13, build 4484c46d9d\n\n$ docker-compose --version\ndocker-compose version 1.27.4, build 40524192\n```\n### Quick Start Guide\n\nThis section contains the minimal set of commands as described below to get the \nexamples and tests working. For explaination of these commands and trouble \nshooting see full installation and setup sections below.\n\n#### Specify the .template files\n\nCopy the template files:\n```bash\ncp .env.template .env\ncp docker-compose.yml.template docker-compose.yml\ncp .test.env.template .test.env\n```\n\nEdit in `.env`:\n```bash\n...\nLOCAL_PACKAGE_DIR=\u003cwhere you cloned the repo\u003e\n...\n```\n\nfor example:\n```bash\n...\nLOCAL_PACKAGE_DIR=/Users/tom.s/projects/building-controls-simulator\n...\n```\n\n#### Run with docker-compose\n\nFirst download latest pre-built container image from Dockerhub:\n```bash\ndocker pull tstesco/building-controls-simulator:0.5.0-alpha\n```\n\nStart container and jupyter-lab server:\n```bash\ndocker-compose up\n```\n\nYou can now run notebooks, start with `demo_LocalSource.ipynb`.\n\n### Local Docker Setup\n\nYou're going to need Docker Desktop installed, if not see https://www.docker.com/. Docker Compose CLI is used to manage the containers and is included by default in the desktop versions of docker for all systems.\n\n### Using Docker-Compose\n\nRequired minimal versions:\n```\n$ docker --version\nDocker version 19.03.13, build 4484c46d9d\n\n$ docker-compose --version\ndocker-compose version 1.27.4, build 40524192\n```\n\n`docker-compose.yml` defines the Dockerfile and image to use, ports to map, and volumes to mount. It also specifies the env file `.env` to inject environment variables that are needed both to build the container and to be used inside the container. As a user all you need to know is that any API keys or GCP variables are stored here (safely) the default EnergyPlus version is 9-4-0, and this can be changed later very easily. \n\nCopy the template files and fill in the variables mentioned below:\n```bash\ncp .env.template .env\ncp docker-compose.yml.template docker-compose.yml\n# and if you want to run the tests\n# .test.env does not need to be editted, unless you want to inject creds\ncp .test.env.template .test.env\n```\n\n**Note**: `docker-compose` behaviour may be slightly different on your host OS \n(Windows, Mac OS, Linux) with respect to how the expansion of environment \nvariables works. If the base `docker-compose.yml` file fails on interpreting \nvariables, try inlining those specific variables, e.g. replacing `${LOCAL_PACKAGE_DIR}` \nwith `\u003cwhere you cloned the repo to\u003e/building-controls-simulator` for example,\n`LOCAL_PACKAGE_DIR=/Users/tom.s/projects/building-controls-simulator`.\n\nEdit in `.env`:\n```bash\n...\nLOCAL_PACKAGE_DIR=\u003cwhere you cloned the repo\u003e\n...\n```\n\nfor example:\n```bash\n...\nLOCAL_PACKAGE_DIR=/Users/tom.s/projects/building-controls-simulator\n...\n```\n\nNow you're ready to build and launch the container!\n\nIf you delete the docker image just go through the setup here again to rebuild it.\n\n### Pull Docker image from Dockerhub\n\nYou can access the latest release image from: https://hub.docker.com/r/tstesco/building-controls-simulator/tags via CLI:\n\n```bash\ndocker pull tstesco/building-controls-simulator:0.5.0-alpha\n```\n\nIf you are using the Dockerhub repository make sure that your `.env` file contains\nthe line\n```bash\nDOCKERHUB_REPOSITORY=tstesco\n```\n\nThis allows `docker-compose.yml` to find and use the correct image. Change this\nline in `docker-compose.yml` if you want to use a locally built image.\n\n```yml\n    # change this if want to build your own image\n    image: ${DOCKERHUB_REPOSITORY}/${DOCKER_IMAGE}:${VERSION_TAG}\n```\n\nto\n\n```yml\n    # change this if want to build your own image\n    image: ${DOCKER_IMAGE}:${VERSION_TAG}\n```\n\n##### Note: Locally built Docker images may use up to 10 GB of disk space - make sure you have this available before building.\nThe size of the container image can be reduced to below 5 GB by not installing\nevery EnergyPlus version in `scripts/setup/install_ep.sh` and not downloading \nall IECC 2018 IDF files in `scripts/setup/download_IECC_idfs.sh`. Simply comment\nout the versions/files you do not need in the respective files.\n\n## Run BCS with Jupyter Lab Server (recommended: option 1)\n\nA jupyter-lab server is setup to run when the container is brought up by `docker-compose up`. This is accessible locally at: http://localhost:8888/lab. \n\n`docker-compose up` will also build the image if it does not exist already, and then run `scripts/setup/jupyter_lab.sh`.\n\nStopping or exiting the container will also shutdown the jupyter-lab server.\n\n```bash\ndocker-compose up\n```\n\nThe container can be shutdown using another terminal on the host via:\n\n```bash\ndocker-compose down\n```\n\n#### Configure EnergyPlus version\n\nUsing this flow of `docker-compose up` and `docker-compose down` you can \nmodify the `scripts/setup/.bashrc` file line that targets the EnergyPlus\nversion, by default this is \"8-9-0\" which is the minimum version supported.\n\n```bash\n. \"${PACKAGE_DIR:?}/scripts/epvm.sh\" \"\u003cx-x-x\u003e\"\n```\n\n## Run BCS with interactive bash shell (alternative: option 2)\n\nThe `docker-compose run` command does most of the set up and can be used again \nto run the container after it is built. The `--service-ports` flag should be set \nto allow access on your host machine to jupyter-lab, see: https://docs.docker.com/compose/reference/run/\n\n```bash\n# this command runs the container and builds it if it cannot be found (only need to do this once!)\n# this will take ~30 minutes, mostly to download all desired versions of EnergyPlus\n# perfect opportunity for a coffee, water, or exercise break\ndocker-compose run --service-ports building-controls-simulator bash\n\n# select the version of EnergyPlus to use in current environment, this can be changed at any time\n# EnergyPlus Version Manager (epvm) script changes env variables and symbolic links to hot-swap version\n# by default .bashrc sets version to 9-4-0.\n. scripts/epvm.sh 9-4-0\n\n# you're done with container setup! now exit container shell or just stop the docker container\n# unless you specifically delete this docker container it can be restarted with the setup already done\nexit    # first exit to get out of pipenv shell\nexit    # second exit to get out of container shell\n```\n\nThere is also a background script `scripts/setup/jupyter_lab_bkgrnd.sh` \nif you would like to run the jupyter-lab server from bash tty and keep your \nprompt available.\n\n```bash\ndocker-compose run --service-ports building-controls-simulator bash\n# in container, enter virtual env\npipenv shell\n# then start jupyter lab server in background\n. scripts/setup/jupyter_lab_bkgrnd.sh\n```\n\n### Open bash shell in running container\n\nIf you've run the container with `docker-compose up` or `docker-compose run` \nand need an interactive bash shell inside, lookup the container id with \n`docker ps` then run:\n\n```bash\ndocker exec -it \u003crunning container id\u003e bash\n```\n\n## Authentication with GCP\n\nGCP credentials are not required to use the BCS but make accessing data much\neasier. If you do not have credentials but have local access to data see \nsection below.\n\nFirst authenticate normally to GCP, e.g. using `gcloud auth`. Then copy `${GOOGLE_APPLICATION_CREDENTIALS}` into the container to access GCP resources with \nthe same permissions.\n\nOn host machine:\n```bash\n# on local machine copy credentials to container\ndocker cp ${GOOGLE_APPLICATION_CREDENTIALS} \u003ccontainer ID\u003e:/home/bcs/.config/application_default_credentials.json\n```\n\nWithin container:\n```bash\n# in container make sure bcs user can read credentials\nsudo chown \"bcs\":\"bcs\" ~/.config/application_default_credentials.json\n```\n\n## Using locally cached data\n\nInstead of using GCP access to download data you can use a locally cached\nDYD files following the format: `data/input/local/\u003chashed ID\u003e.csv.zip`.\nThese data files are the time series measurements for an individual building.\n\nSimply save the files using this format and you can use them in local simulations.\n\nSee `src/python/BuildingControlsSimulator/DataClients/test_LocalSource.py` and\n`notebooks/demo_LocalSource.ipynb` for example usage.\n\n## Docker Issues\n\nSome issues that have occurred on different machines are:\n\n### Build issues\n\n- incompatible versions of Docker and Docker Compose (see requirements above).\n- `.env` variables unset, make sure all `.env` variables not specified in `.env.template` are matched correctly to your host system.\n- windows line endings in `.env` file.\n- `apt-get install` failing or other packages not being found by apt-get\n    - Verify network connection and build container again\n- `jupyter lab build` failing\n    - try setting in Dockerfile command `jupyter lab build --dev-build=False --minimize=False`.\n\n### Troubleshooting file permissions issues\n\n1. After switching branches on host machine mounted volumes give permissions\nerrors when access is attempted within docker container.\n    - on Mac OS permissions for Full Disk Access must be given to Docker App. \n    This is found in Settings \u003e Security \u0026 Privacy \u003e Full Disk Access. See answer 1 in https://stackoverflow.com/questions/64319987/docker-compose-volume-started-acting-weird-no-permissions-on-files-after-switch\n2. After making any changes to docker, restart the docker desktop daemon.\n3. Even if you didn't make an changes, stopping your container, restarting your terminal,\n    and restarting the docker daemon, then restarting the container can alleviate issues.\n\n## Usage\n\n### Example Notebook (Hello World): demo_LocalSource.ipynb\n\nOpen in jupyterlab `notebooks/demo_LocalSource.ipynb` and run all cells.\nThis demo shows the usage of the building controls simulator and will download \nnecessary data from www.energyplus.net and generate input data for the simulation.\n\n### Example Notebook with Donate Your Data (DYD): demo_GCSDYDSource.ipynb\n\nSupport for ecobee Donate Your Data (DYD) is included with the GCSDYDSource. \nFor example usage see `notebooks/demo_GCSDYDSource.ipynb`.\nThe `GCSDYDSource` supports using a local cache of the data files. Simply copy them using \nformat `data/cache/GCSDYD/\u003chash ID\u003e.csv.zip`, for example:\n\n```bash\n$ ls data/cache/GCSDYD\n2df6959cdf502c23f04f3155758d7b678af0c631.csv.zip\n6e63291da5427ae87d34bb75022ee54ee3b1fc1a.csv.zip\n4cea487023a11f3bc16cc66c6ca8a919fc6d6144.csv.zip\nf2254479e14daf04089082d1cd9df53948f98f1e.csv.zip\n...\n```\n\nFor information about the ecobee DYD program please see: https://www.ecobee.com/donate-your-data/.\n\n### Development setup - Using VS Code Remote Containers\n\nHighly recommend VS Code IDE for development: https://code.visualstudio.com/download\nIf you're not familar with VS Code for Python develpoment check out this guide and [PyCon talk](https://youtu.be/WkUBx3g2QfQ) and guide at: https://pycon.switowski.com/01-vscode/\n\nThe Remote Containers extension adds the Remote Explorer tool bar. This can be used to inspect and connect to available Docker containers.\n1. `docker-compose up` to run the `building-controls-simulator` container.\n2. Right click on `building-controls-simulator` container (will be in \"Other Containers\" first time) and select \"Attach to Container\". This will install VS Code inside the container.\n3. Install necessary extensions within container: e.g. \"Python\" extension. The container will be accessible now in \"Dev Containers\" section within Remote Explorer so the installation only occurs once per container.\n4. Use the VS Code terminal to build and run tests, and edit files in VS code as you would on your host machine.\n\n### Deleting and rebuilding the container\n\nShould something go wrong with the container or it experience an issue during the build remove the broken containers and images with these docker commands:\n\n```bash\n# first list all containers\ndocker ps -a\n\n# stop containers if they are still running and inaccessible\ndocker stop \u003ccontainer ID\u003e\n\n# remove containers related to failed build\ndocker rm \u003ccontainer ID\u003e\n\n# list docker images\ndocker images\n\n# remove docker image\ndocker rmi \u003cimage ID\u003e\n```\n\n### Run container with interactive bash tty instead of auto-starting jupyter-lab\n\nStart bash tty in container:\n```\n# --rm removes container on exit\n# --service-ports causes defined ports to be mapped\n# --volume maps volumes individually\nsource .env\ndocker-compose run \\\n    --rm \\\n    --service-ports \\\n    --volume=${LOCAL_PACKAGE_DIR}:${DOCKER_PACKAGE_DIR}:consistent\\\nbuilding-controls-simulator bash\n```\n\nThe advantage over using docker run (though very similar) is automatic sourcing\nof the .env environment variables and ports configured in `docker-compose.yml`.\n\n### Run container without docker-compose\n\nKeep in mind this will not mount volumes.\n\n```bash\ndocker run -it -p 127.0.0.1:8888:8888 \u003cIMAGE_ID\u003e bash\n```\n\nJupyterlab needs to be run with:\n```bash\njupyter-lab --ip=\"0.0.0.0\" --no-browser\n```\n\n### Run the tests\n\nTest files are found in src/python directory alongside source code, they are identified by the naming convention `test_*.py`.\nThe `pytest` framework used for testing, see https://docs.pytest.org/en/stable/ for details.\n\nSimilarly to the `.env` file, you can set up `.test.env` from `.test.env.template`.\nThen simply run the `test_env_setup.sh` script to set up the test environment.\n\n```bash\n. scripts/setup/test_env_setup.sh\n```\n\nFinally, run all the tests:\n```bash\npython -m pytest src/python\n```\n\n## Changing dependency versions\n\nThe dependencies are pinned to exact versions in the `requirements.txt` file.\nTo change this simply change line (approx) 124 in the `Dockerfile` from:\n```\n    \u0026\u0026 pip install --no-cache-dir -r \"requirements.txt\" \\\n    # \u0026\u0026 pip install --no-cache-dir -r \"requirements_unfixed.txt\" \\\n```\n\nto\n\n```\n    # \u0026\u0026 pip install --no-cache-dir -r \"requirements.txt\" \\\n    \u0026\u0026 pip install --no-cache-dir -r \"requirements_unfixed.txt\" \\\n```\n\nThis will install the latest satisfying versions of all dependencies. After testing that\nthe dependencies are working freeze them into a new `requirements.txt` file.\n\n```\npip freeze \u003e requirements.txt\n```\n\nSeveral dependencies are installed from source so these must be removed from the\n`requirements.txt` file. These may be:\n\n```\nPyFMI\nAssimulo\nhpipm-python\n```\n\nThen change line 124 in the `Dockerfile` back to use the `requirements.txt` file.\nNote that when building the image using the `requirements.txt` file it will \nadd the pinned dependencies to the Pipfile, discard those changes.\n\n## Making a Release\n\n1. Commit changes to master, reference new version number.\n2. Increment version number in `.env.template` and `setup.py`. Use semver (https://semver.org/) convention for release versioning.\n3. On GitHub use the releases/new workflow (https://github.com/ecobee/building-controls-simulator/releases/new). \n4. Build docker image locally.\n5. Run tests.\n6. Tag release\n    ```bash\n    docker tag \u003cIMAGE_ID\u003e tstesco/building-controls-simulator:\u003cVERSION\u003e\n    ```\n7. Push docker image to dockerhub (https://hub.docker.com/repository/docker/tstesco/building-controls-simulator)\n    ```bash\n    docker push tstesco/building-controls-simulator:\u003cVERSION\u003e\n    ```\n\n## Weather Data\n\nThere are several data sources that can be used. The `WeatherSource` provides methods\nto get weather data required for simulations and preprocess it for use in simulation.\n\nThe Energy Plus Weather (EPW) format is used and is described in the linked NREL \ntechnical report: https://www.nrel.gov/docs/fy08osti/43156.pdf\n\n### EnergyPlus EPW Data\n\nThe simpliest data source for EPW formated TMY data is from the EnergyPlus website:\nhttps://energyplus.net/weather.\n\n### NREL NSRDB\n\nThe current NSRDB has TMY and PSM3 data available through its developer API. \nThis however does not contain all fields required by the EPW format so those fields\nmust be back filled with archive TMY3 data from the nearest weather station.\n\nNSRDB PSM3: https://developer.nrel.gov/docs/solar/nsrdb/psm3-download/\nNSRDB PSM3 TMY: https://developer.nrel.gov/docs/solar/nsrdb/psm3-tmy-download/\n\n### CDO: https://www.ncdc.noaa.gov/cdo-web/\n\nFor potential future integration.\n\n### Configuration\n\nThe .bashrc at `scripts/setup/.bashrc` can be configured similar to any .bashrc file.\nIt simply runs commands (rc) whenever an interactive bash shell is opened.\n\n## Building the Documentation\n\nTo build documentation in various formats, you will need [Sphinx](http://www.sphinx-doc.org) and the\nreadthedocs theme.\n\n```\ncd docs/\nmake clean\nmake html\n```\n\nThe html files are then available in `docs/build/html`. Open the root file `index.html` \nin a web browser to view them locally.\n\n## External Tools\n\n- EnergyPlus: https://github.com/NREL/EnergyPlus\n- PyFMI: https://github.com/modelon-community/PyFMI\n- EnergyPlusToFMU: https://github.com/lbl-srg/EnergyPlusToFMU\n- Eppy: https://github.com/santoshphilip/eppy\n- fmi-library: https://github.com/modelon-community/fmi-library\n- FMUComplianceChecker: https://github.com/modelica-tools/FMUComplianceChecker\n\n## Contributing\n\nSee notes on how to develop this project in [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Communication\n\nGitHub issues: bug reports, feature requests, install issues, RFCs, thoughts, etc.\n\n## License\n\nBuilding Controls Simulator is licensed under a BSD-3-clause style license found in the [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecobee%2Fbuilding-controls-simulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecobee%2Fbuilding-controls-simulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecobee%2Fbuilding-controls-simulator/lists"}