Build Your First UBEM with EnergyAtlas¶

This tutorial will guide you through creating your first Urban Building Energy Model (UBEM) using EnergyAtlas.

Prerequisites¶

Before starting, ensure you have:

• EnergyAtlas installed (Installation Guide)
• Basic understanding of UBEM concepts (UBEM Fundamentals)
• Building data for your study area (building footprints, assessor data, or similar)

Step 1: Prepare Your Data¶

Required Data¶

• Building footprints: Shapefile or GeoJSON with building geometry
• Building attributes: Age, use type, floor area, number of stories
• Weather data: TMY or EPW weather file for your location

Data Preparation¶

1. Organize your building data into a single file
2. Ensure coordinate system is consistent (preferably WGS84 or local UTM)
3. Clean data: remove duplicates, fix geometry errors
4. Validate attribute fields

Learn more: Data Preparation Guide

Step 2: Create a New Project¶

1. Open EnergyAtlas
2. Click "New Project"
3. Enter project name and location
4. Select coordinate system matching your data

Step 3: Import Building Data¶

1. Navigate to Urban Data Integration workflow
2. Click "Import Data"
3. Select your building footprint file
4. Map attribute fields to EnergyAtlas data model
5. Review imported buildings

Learn more: Urban Data Integration Workflow

Step 4: Assign Building Archetypes¶

1. Navigate to Template Definition and Assignment workflow
2. Browse available archetypes from the library
3. Create assignment rules based on building characteristics
4. Review and adjust assignments as needed

Learn more: - Template Definition and Assignment Workflow - Archetype Library

Step 5: Run Simulation¶

1. Navigate to Running and Calibrating workflow
2. Select weather file for your location
3. Configure simulation parameters
4. Click "Run Simulation"
5. Monitor progress

Learn more: Running and Calibrating Workflow

Step 6: View Results¶

1. Navigate to Results View workflow
2. Explore energy consumption by:
3. Building use type
4. Building age
5. Geographic location
6. Export results for further analysis

Learn more: Results View Workflow

Next Steps¶

• Create Scenarios: Model retrofit measures and policy scenarios
• Scenario Design and Simulation Workflow
• Calibrate Model: Improve accuracy using observed data
• Running and Calibrating Workflow
• Explore Advanced Features:
• EnergyAtlas Objects Guide
• Technical References

Troubleshooting¶

Common issues and solutions:

• Import errors: Check data format and coordinate system
• Missing archetypes: Create custom archetypes or use library templates
• Simulation failures: Verify weather file compatibility and building assignments

Need help? Check the FAQ or open an issue on GitHub.

---

Last updated: January 2026