{"id":16838197,"url":"https://github.com/jlfwong/hvac-sim-app","last_synced_at":"2025-06-25T06:04:16.784Z","repository":{"id":232875146,"uuid":"748562612","full_name":"jlfwong/hvac-sim-app","owner":"jlfwong","description":"A library for modeling loads and costs for heat pumps, furnaces, air conditioners etc","archived":false,"fork":false,"pushed_at":"2024-04-30T15:17:16.000Z","size":3052,"stargazers_count":8,"open_issues_count":1,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-10T11:34:59.209Z","etag":null,"topics":["climate","heatpump","heatpumps","simulation","utility-bills"],"latest_commit_sha":null,"homepage":"https://shouldiheatpump.ca/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlfwong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-26T09:01:57.000Z","updated_at":"2025-04-07T18:30:28.000Z","dependencies_parsed_at":"2024-11-24T08:50:51.665Z","dependency_job_id":null,"html_url":"https://github.com/jlfwong/hvac-sim-app","commit_stats":null,"previous_names":["jlfwong/hvac-sim-app"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jlfwong/hvac-sim-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlfwong%2Fhvac-sim-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlfwong%2Fhvac-sim-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlfwong%2Fhvac-sim-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlfwong%2Fhvac-sim-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlfwong","download_url":"https://codeload.github.com/jlfwong/hvac-sim-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlfwong%2Fhvac-sim-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261816306,"owners_count":23213862,"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":["climate","heatpump","heatpumps","simulation","utility-bills"],"created_at":"2024-10-13T12:21:31.444Z","updated_at":"2025-06-25T06:04:16.767Z","avatar_url":"https://github.com/jlfwong.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HVAC Simulator\nThis repository contains code to simulate HVAC systems (e.g. heat pumps) for homes to evaluate their utility costs and\ngreenhouse gas emissions using real historical weather data.\n\nYou can try it out on https://shouldiheatpump.ca/\n\n\u003cimg width=\"1334\" alt=\"image\" src=\"https://github.com/jlfwong/hvac-sim-app/assets/150329/b1acc7cb-14d1-4e41-b689-d5bdb8a83795\"\u003e\n\nThe idea and implementation were inspired heavily by https://heatpumpshooray.com/\n\n## How does it work?\n\nThis repository contains two main things: an HVAC simulation library, and a web\napplication for a heat pump calculator.\n\n### The simulation library\n\nThe HVAC simulation library simulates on a 20 minute time step over long spans\nof time (up to a year with current weather data).\n\n\u003cimg width=\"392\" alt=\"image\" src=\"https://github.com/jlfwong/hvac-sim-app/assets/150329/38cb778c-273d-4e7f-8e74-6d149bd39d74\"\u003e\n\nAt each time step, the simulator...\n\n1. Uses a simulated thermostat to decide whether to turn heating or cooling\n   equipment on or off based on historical weather data and a simulated internal\n   temperature.\n\n2. If equipment is turned on, the simulator calculates the BTU/hr thermal power\n   of each appliance, along with its fuel usage (electricity, gas, etc.)\n\n4. Based on a model of building geometry, weather conditions, and time-of-day,\n   the passive thermal loads on the house are calculated in BTU/hr. This includes\n   conduction, convection, infiltration, solar gain, and occupant body\n   heat.\n\n5. At the end of each time step, the BTU/hr from the HVAC equipment and the BTU/hr\n   from passive thermal loads are multiplied with the duration of the timestep to\n   get a net BTU change for the time step. Using an estimated thermal mass of the\n   house, this is used to update the indoor air temperature for the next time step.\n\n6. At the end of each time step, energy usage is recorded into monthly bills, using\n   configurable utility tariffs.\n\nAt the end of the simulation, utility bills are tabulated, and emissions are\ncalculated based on fuel usage.\n\nThe library is designed to be extremely flexible. Custom HVAC devices can be\ncreated, custom thermostat algorithms can be applied, and time-of-use pricing\ncan be implemented for utility bills.\n\n### The heat pump calculator web app\n\nThe web app uses the above simulation library to calculate utility bills for\nCanada on https://shouldiheatpump.ca/. To set up the simulation, we gather\nweather and utility cost information for Canada, and automatically select \nan air-sourced heat pump based on the specific situation of the simulated home.\n\nWeather information was sourced from the [ECMWF ERA5 hourly dataset](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-pressure-levels?tab=overview).\n\n2023 weather data for the majority of Canada was downloaded as a 2GB binary file,\nthen split into many JSON files (one per 3-letter prefix of a postal code),\ncompressed, and uploaded to S3. This allows the web app to use real weather data\nwithout needing a server.\n\nPerformance data for heat pumps is sourced from the [NEEP Cold Climate Air Source Heat Pump Database](https://neep.org/heating-electrification/ccashp-specification-product-list).\n\n## Why make this?\n\nThere are many heat pump calculators out in the wild, though none I could find\nseemed accurate and open source. While this repository is designed with Canada\nin mind, the core simulation library should work anywhere in the world.\n\nIf you're motivated to get a version of this calculator working in your country,\nfeel free to fork this repository and make it happen!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlfwong%2Fhvac-sim-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlfwong%2Fhvac-sim-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlfwong%2Fhvac-sim-app/lists"}