Quantum Documentation
Intro to Quantum
Why a new Standard?
The majority of smart building applications (and standards) in the marketplace today are designed around characterizing the controls and sensors of a building according to existing paradigms. These existing paradigms include: reactive (PID) and thermostatic controls, static sequences of operation, manual system commissioning, and SaaS overlay analytics applications. Physics based modeling of systems has been an entirely different discipline in its own right (Modelica, EnergyPlus, and others), and has mostly been limited to usage for early stage analysis of designed building performance. It is rare for physics-based energy models to see any usage into the operational stage of a building. Building Information Modeling (BIM) has a typical life cycle similar to energy models—if it is used during the design phase, it is also rare for it to find any usage in the operational phase of a building.
This isn’t to say that these existing standards and data models don’t have their own place, but in our investigation of standards related to modeling buildings, sensors, controls, or the physics of components and systems, there wasn’t anything out there that was:
1) looking at it from the perspective of autonomous controls and systems engineering,
2) tying the necessary aspects together holistically.
For example, in Haystack or Brick, we might say a sensor is in a zone, but that doesn’t tell an installer (or a self-commissioning system) where specifically that sensor is intended to be in 3D space. A zone being on a floor doesn’t convey where it exists in 3D space, nor the adjacencies of the surfaces in that zone to other surfaces and the likely heat transfer interactions that would occur. Semantically labeling something as a “pump” provides no notion of the role of that thing in a system, nor of the energy flows into and out of that thing. Providing a Modbus map or a BACnet points list doesn’t tie the sensor or control interfaces of a controllable system back to the physical piece of equipment being controlled.
So we decided to create a new approach with key collaborators, with the intention of capturing the concepts necessary for autonomous control; it’s called Quantum.
Quantum Basics
Quantum is a physics-based description language for autonomous systems. It organizes the fundamental pieces of information regarding equipment, buildings, people, and more—into defined relationships across different domains. Quantum is often discussed in a few different contexts; these are expanded upon below.
The Quantum Ontology
The dictionary definition of ontology is “the branch of metaphysics dealing with the nature of being.” We can think of it simply as having to do with identity and purpose; and Quantum as an ontology is primarily focused on answering the questions of “what do I do?,” and “how do I do it?” for all the things that are used in and around systems. This gets us away from focusing our time and attention on “what is this thing called?,” to focusing on “how do things work quantitatively?.”
A Systems Perspective
It is critical to maintain a systems theory perspective when learning about Quantum. When engineers design and build systems, either for an HVAC application or another industrial process, things are always placed into a system with intent.
Let’s just take the simple hydronic loop shown below. It has a boiler, a pump, a radiator, and some pipes connecting them. Start off by answering the question of “what is this system designed to do?” and “what are each of the things in the system supposed to accomplish?.” This example is straight forward—the goal of the system is to maintain some thermal condition of the radiator; the boiler is designed to provide thermal energy to the radiator; the pump is designed to overcome pressure losses in the system in order to actually transport the thermal energy; and the pipes provide pathways for the media carrying the thermal energy. If any of those things were missing from the system, it would be incomplete and non-functional per its design intent.
Actors, Quanta, and Behaviors
Understanding the intended role of something in a system is what led us to the creation of actor types. The actor type characterizes the intended role of a thing in a system. Going back to the example above, we characterize the pump as a transport actor, since its intended role is to move liquid throughout the system. This leads us directly into the concept of quanta types. We think about quanta as packets of substance that are exchanged by systems. Quanta themselves are mostly a pairing of a specific quanta type and a media. In the example above, the media being circulated might be water, and the quanta type would be a liquid; we would refer to this as a liquid quanta with a water media. As the quanta marches around the system above, its stateful properties are manipulated (or transformed) by the different components. The transform that acts on the properties of a quanta is called a behavior.
Composable Components
Up until this point, we’ve been referring to the things in systems very generically; let’s clarify that. The fundamental building block of autonomous systems in Quantum is the equipment component (component). We frame the identity of a component based on: 1) actor type, 2) quanta type, 3) behaviors, 4) properties. We parameterize the physical attributes of a component via properties, which can be either literal values or computed via an equation. For example, we might define the diameter of a pump impeller as a property (d) with a literal value (for example, 4 inches), but define the circumference of the pump impeller as a property of the pump computed via an equation (π*d). Once the identity of the component is framed, incoming and outgoing connection nodes are added to the component, which define the required quanta types. Components are then wired together to create equipment and equipment is wired together to create systems. Closed loops between the connections of components are used to infer systems, subsystems, and overall topology. The requirements placed on component connectivity enables components to be reused across different equipment and system topologies.
The Quantum Object Model
Quantum as an information model is based on objects and relations (an object graph), where objects have attributes. An object type in Quantum represents some modular concept in the ontology: a building, a floor of a building, a component of some equipment, or a medium representing a type of liquid. A relation type describes some kind of relationship between two objects. An object may be related to other objects in very specific ways, depending on the object types being related. Relating this back to object oriented programming, an object type is analogous to a class, and an object1 analogous to an instance of a class. Objects and relations are analogous to nodes and directed edges in a graph theory framework. Quantum is more akin to a labeled property graph than a semantic graph2.
Domains
We organize the different types of objects into domains. The domains are intended to group object types in a meaningful way. This was motivated by our experience attempting to use different data standards, whose definitions and documentation were primarily flat and required digging to understand how things related to one another. A brief summary of the different domains is provided in the table below.
DOMAIN
OVERVIEW
Site
The site domain captures high-level geographic object types and situates a building in the world.
People
If it weren’t for people, buildings wouldn’t exist. Users and organizations are the two primary object types in this domain. In deconstructing how users interact and engage with buildings (and the things inside them) as well as when they interact with them (at what point in the life cycle), there are many different needs and personas. Users are related to organizations, sites, and other object types in Quantum via different roles.
Asset
Asset management is an important aspect of owning and operating Buildings. Assets are related to users, organizations, and buildings in different ways. An asset might be the throughput of a warehouse, but it may be owned by some external organization. Oftentimes, assets have particular needs or environmental constraints (must be kept frozen, etc.).
Environment
Buildings exist and operate in many different environments. From a system modeling perspective, it’s crucial to know where a building is located, as this is used to understand the environmental conditions in which it operates.
Building
Understanding the physical construction and topology of a building is a key aspect of implementing autonomous control. The building domain includes floors, zones, surfaces, layers, all of which are characterized with different properties.
Geometry
A building must be able to reconstruct the 3D landscape that it operates in. Equipment and assets need to be located at some point in space (a sensor on a wall, an air terminal in the ceiling). Shapes and vertices are the key object types in this domain, enabling 3D reconstruction of physical spaces and things.
System
Systems are key for autonomous control, as they capture an interconnected group of equipment. From this interconnectedness and the designated roles of the equipment in the system, an autonomous agent can deduce subsystems, loops, and operational constraints for the system and its contained equipment.
Equipment
Equipment, components, and connection nodes are the backbone of this domain. A component is the fundamental building block in Quantum, and is an object that can explain its identity. The identity is determined by the components’ specified actor and quanta type on which it acts. System topology is determined by the interconnectedness of components, both within and across equipment boundaries.
Quanta
Understanding energy flows between buildings and systems is very dependent on the media, state of that media, and flow of that media. This domain includes quanta, which are defined as packets of substance exchanged between and operated on by components. They are often thought of as the things that capture state information.
Property
Components define their operational characteristics through a series of properties and behaviors. Behaviors are transform operators that act on the properties of a quanta, capturing what a component does. A property is a generic numeric quantity that can be associated with many different types of objects. Similar to a variable in a programming language, a property can be computed (via a series of operators, literals, or other properties) or can have a literal value. When properties are computed, this information is captured in an equation.
TimeSeries
Autonomous systems require the ability to understand and learn from the past and understand what the future may hold. Historical or predicted values of properties and events are captured in this domain.
Event
Autonomous systems in industrial environments require decentralized orchestration and computing. Additionally, alerting based on observed data patterns and notifications of relevant parties for time-sensitive error resolution is captured in this domain.
Binding
A category of object types that can be generically associated with other objects for the purposes of conveying metadata. These objects can be thought of similarly to MIME types.
Properties
Properties are used frequently in Quantum as a generic mechanism to associate quantitative attributes to objects. Properties can have units (or be dimensionless), and can have a literal value or be computed by a series of operators, literals, or other properties. For example, we may wish to express the area, height, and volume (three different properties) of a zone. In a simplistic calculation, we might say that the zone volume property is computed via the expression: volume=area*height, where both area and height are properties with literal numeric values. Quantum’s property and equation object types enable users to express simple and complex mathematical relationships. In addition to a current value, properties can have both historical data (a history) or predicted data (a prediction).
A deeper dive on properties, behaviors, equations and time-series data is forthcoming, however, the primary concept to understand right now is that a property can be associated with many different object types in Quantum.
Site, Environment, and Building
The site, environment, and building domains are highly related to one another. A site has one or more buildings and is associated with a location object type in the environment domain. A building has one or more floors (or stories), each floor has one or more zones (or spaces), a zone has some number of surfaces, surfaces are composed of constructions and layers, which then have an associated media. The design goal for the different object types in the building domain is to capture information pertaining to three primary aspects of a building: the architectural representation (form), the functional representation (purpose), and the thermal representation (energy balance). Other information models may consider one or two of these aspects, leading to the creation and maintenance of multiple building representations throughout the building design process. Our goal in Quantum is to strike the correct balance.
The architectural form of the building provides detailed 3D geometry and information about materials; the functional representation enables understanding of the design intent for different areas of the building; the thermal representation derives from the architectural form and the function of building areas to enable understanding of how energy moves throughout the building. A deeper dive on understanding the thermal and functional representation of a building (constructions, layers, and media) is forthcoming; the following section on geometry provides an introduction to how 3D geometry is represented in Quantum.
The site has a location, which captures the address, elevation, and other geographic information. Since the environment that a building operates in is critical for optimizing equipment operations and achieving its goals, a location should always be associated with at least one weathersource, although multiple weathersources can be used. For example, at the beginning of a project we may know the location of a building, and associate a static TMY33 file as a weathersource for that building. Further in the process, someone may wish to add a near real-time weather api as a weathersource for a building—both of these are possible with Quantum.
Zones
The basic element of our building geometry representation is the zone (architectural space), which represents a portion of the building dedicated to a purpose. A key design goal for representing spaces in Quantum was to focus on defining spaces that exist entirely in their own right, without knowing it’s location or context in the building. Rather than spaces being derived from walls, surfaces, or vertices, the shape of the space is defined first, and in coordination with other spaces in the building, the walls, surfaces, and adjacencies are actually derived from the intersection of spaces. Spaces are usually defined by the areas encapsulated by the constructed (physical) walls of the building, such as a typical office. However, building spaces don’t always break up according to physical boundaries and often require logical boundaries. We conceptualize logical boundaries as an “air boundary.”
Geometry
Vertices and Shapes
The basic geometric concept is a shape. A shape is an ordered list of vertices that are connected together. The ordering is very important, as it defines the path of traversal for the shape, enabling both convex and concave shapes. The vertices usually lie in a flat 2D plane. They can either be a loop (closed) or have start and end points (open). The shape concept is also called a path, poly line, or contour in other software (analogous concepts can be found in IFC, EnergyPlus, AutoCAD, SVG, and others). Note that shapes are similar to polygons, but are not necessarily composed entirely of straight line connections. There may be a curve connecting two vertices instead of a straight line.
The key advantage of this structure is that it conveys adjacency information and in the closed case has an inside/outside. We know which segments are connected together. We can query whether points are in the shape. Shapes are used in a variety of ways throughout Quantum; a few examples include: 1) defining floor plans, 2) defining custom shaped apertures, 3) defining sub-surface geometry.
Floor Plan Shapes
The primary use of shapes for us is to describe the floor plan of a space. In this case each vertex represents the beginning of a wall around the loop. The length of the wall is determined by the distance to the next vertex. The loop encloses the boundary of the space, and is often referred to as the boundary shape. The boundary shape determines the floor plan of any particular zone. The floor plan is then extruded by a height to get the shape of the room. The exact shape of each wall, as well as the floor and ceiling is implicit in this model. You must refer to the context of the wall in the shape to understand its length and height.
Surfaces
A surface is a logical piece of construction in a space such as a wall, door, or window. Whereas shapes are very concrete in the sense that they exist as they are being defined, surfaces are more conceptual because they are really a consequence of the geometry definition, meaning, they only exist after the geometry is defined. Even within the realm of surfaces, there are certain surface types that are more conceptual than others. For example, the only purpose of a boundary surface is to capture the shape of the space, whereas other surface types are intended to convey thermal characteristics of the surface (layers, and others). The surface type is the mechanism used to convey the purpose of a surface. There currently exist 11 different surface types:
Primary Surface Types
Wall, Floor, Ceiling, Roof, BasementWall, Slab
Fenestration Surface Types
Door, Glazing, GlassDoor
Conceptual Surface Types
Boundary, SubSurface
Surfaces are related to one another via two primary mechanisms:
A surface is related to the vertex contained by another surfaces’ shape. For example, this is how a wall surface is related to a boundary surface of a space. We refer to these as surfaces along the boundary path.
Surfaces are related to one another via an adjacency. This is how fenestration (windows, doors) are related to a wall, or how subsurfaces are related to a parent surface (more details on this later).
Adjacencies
Surfaces can be adjacent to other surfaces, but adjacencies are a more generic tool for relating things to surfaces. For example, they enable us to relate an equipment or component to a surface. More details on how the exact location of an arbitrary thing is specified in relation to a surface will come later.
Multiple Spaces and the Role of SubSurfaces
So far, we have mostly focused on how surfaces and shapes relate to a building composed of a single space, but this is not a very realistic picture of a building. When we begin looking at buildings having multiple zones, intersections between surfaces become very important.
A few crucial points to reiterate before diving into this topic:
Spaces are defined entirely from the inside
The majority of the geometry definition of a space can be traced back to a single boundary shape, with all of the surfaces occurring as a consequence of this boundary shape definition.
This is what enables us to move spaces around in 3D very freely. The wall surfaces of a space are really just a consequence of the boundary shape definition—they do not depend on how two spaces are situated in relation to one another. That said, certain information only becomes known when spaces are placed in 3D space relative to one another. This is the case for surface intersections, as demonstrated below.
This is the primary role that subsurface surface types play—they are surfaces that are derived based on intersections of other surfaces. This occurs with:
Floors intersecting ceilings of spaces below them
Walls intersecting walls of neighboring spaces
Some important characteristics of subsurfaces:
Subsurfaces are algorithmically generated, not user defined.
Subsurfaces represent a portion of a surface between two spaces, or between a space and some external boundary condition (outside, ground). They are adjacent to either one or two surfaces, which are referred to as their parent surfaces.
Subsurfaces do not overlap other subsurfaces. Subsurfaces represent the smallest unit of division. They cannot be the parent adjacency to any other surface.
Subsurfaces have their own shape.
Quantum Explorer
Quantum Explorer is a software tool for exploring the Quantum ontology structure, elements, and relationships. You can navigate Quantum domains, objects, and relationships in the outline view using the Object and Details browsers or visually on the Ontology Graph Explorer. With the Query Builder, you can drag and drop objects and attributes to create a query visually, then use the built-in GraphiQL plugin to see what that query looks like in the Quantum API syntax.
To launch the Quantum Explorer application:
1. At the top of any QuantumAlliance.org page, click Sign in.
2. Create an account by clicking Sign up and following the directions to create your account. Confirm your email using the message you receive.
3. To sign in, enter your username and password.
You can start using Quantum Explorer by clicking the button below but before you do, consider checking out the video and documentation content below.
Quantum Explorer Overview video
Watch this video for an overview of the elements and the workflow of Quantum Explorer.
Query Builder
The Quantum Explorer Query Builder is an interactive tool set for creating and executing textual queries that helps you become familiar with the syntax of the Quantum API. Watch this video for a quick tour of the Query Builder and the built-in GraphiQL interface.
Querying Quantum Walkthrough video
Sample queries
Try the following sample queries yourself in Quantum Explorer using the Query Builder.
Number of floors
How many floors exist in each of the buildings in the demonstration dataset?
1. In Quantum Explorer, click Build Query.
The Query Builder opens on the right.
2. Expand the Building domain, then drag and drop the Building object to the From tray.
3. Drag and drop the Floor object to the To tray.
4. Click Run Query, then view the query and the results.
Number of zones
How many zones exist in each of the buildings in the demonstration dataset?
Try it in Quantum Explorer:
Zone with unlocked data structure
Which zones in the demonstration dataset have a Locked property value of “false?"
1. Expand the Building domain, then drag and drop the Zone object to the From tray.
2. Expand the Property domain, then drag and drop the Property object to the To tray.
3. Click the Property object to open the Details browser, then drag and drop the Locked attribute to the Where tray.
4. Click the Distribution button and select Equal, then enter “false" in the Value field.
5. Click Run Query, then view the query and results.
Site Locations
Where are the sites located in the demonstration dataset?
Try it in Quantum Explorer:
Using Query Chaining to query for zone surfaces
What are the vertices associated with each zone for the buildings in the demonstration dataset, organized by floor?
This is a slightly more advanced query. You need to add a filter to get the zones and surfaces associated with the building floors. All of the object types in this example are from the Building domain.
1. Expand the Building domain and drag the Building object to the From tray. The drag Floor from the same domain to the To tray.
2. Click the chain icon in the lower right corner of the Query Builder to add a query chain. Drag the Zone object to the new To tray.
3. Click the chain icon again to add another query chain, and drag the Surface object to the new To tray.
4. Click Run Query, then view the query and results.
Quantum API
The Quantum API is built on GraphQL, a query language that allows clients to interact with Quantum datasets and query for exactly what they need and nothing more.
HTTP API Overview
An HTTP REST API is provided that supports authentication, user management, and GraphQL access.
The root of this REST API is https://quantumalliance.org/api/
Detailed interactive documentation for all operations is available at https://quantumalliance.org/app/swagger/.
Registering a New User
To create a new account, click the Sign in button on quantumalliance.org, click Sign up, and provide your information. Using the link you receive in an email message, verify your email address to complete the sign up.
Logging In
The GraphQL API endpoints by default use JSON Web Token (JWT) authorization, which ensures that a client has logged into the system before making changes or requesting data.
In order to retrieve a JWT, clients should make a GET request with basic authentication to https://quantumalliance.org/api/auth/login.
For example, from a Unix command line:
This will respond with a JSON object that contains authorization and refresh tokens. The authorization token should be included in requests to the Quantum API.
Generating API Keys
The Quantum API endpoints additionally support the use of API keys, which can be generated with an authenticated request.
For example, from a Unix command line:
This will respond with a JSON object containing an API key linked to the user making the request along with its expiration time. API Keys act with the same permissions as a JWT for the user who generated them would, but provide a longer-lived and more convenient use pattern for command-line and scripting purposes.
Querying with GraphQL
Once an authorization token has been retrieved or API key generated, GraphQL queries can be requested from https://quantumalliance.org/api/graphql.
For example, to query all the sites and their names using an authorization JWT:
Or, the same query using an API Key:
The GraphQL API supports GET and POST request formats. Support for GraphQL subscriptions is available through the https://quantumalliance.org/api/graphqlSubscribe endpoint, which will open a WebSocket. See the Quantum API documentation for more details.
Interactive documentation of the Quantum GraphQL type system is available in the Quantum Explorer app. Users can see what types are available in the API, their specific attributes, and their relationship with other types. This information may also be queried directly from the Quantum API using introspection queries.
Demo Buildings
Demonstration datasets for the following sample buildings are publicly available. Community members are encouraged to interact with the data as a means to further understand Quantum.
Warehouse Building in San Leandro
ATTRIBUTE
DESCRIPTION
Location
San Leandro, CA
Size
Roughly 55,000 square feet
Description
The building is composed of four spaces; two office spaces and two storage spaces. One of the office spaces is on the second story, while all other spaces are on the first. The two storage spaces have dock doors and normal doors interspersed along the ground level.
Floor to Ceiling Height
14 feet in offices; 28 feet in storage areas.
Time-series Data Available
For 2021. Values are stored using SI units.
Zone Sensors
One sensor per zone. Each sensor is mounted to the north facing wall and is modeled as a Quantum equipment. Each sensor equipment has three associated components, one for each of the three air properties being sensed: dry bulb temperature, dew point temperature, and relative humidity.
Weather Data
Oakland, CA
Mechanical Equipment
None
Customer Warehouse 1 in Chicago
ATTRIBUTE
DESCRIPTION
Location
Chicago, IL
Size
454,000 square feet
Description
Box shaped warehouse with trailer docks on the longer sides. A dedicated zone for temperature sensitive inventory located on the south-west corner of the building. The north east corner houses office space and the cafeteria. In all there are 36 dock doors to facilitate the flow of goods in and out of the building. 20 of them are on the south side of the building whereas the rest of them are on the north side.
Floor to Ceiling Height
All spaces have a 40 foot floor to ceiling height.
Time-series Data Available
For 2021. Values are stored using SI units.
Zone Sensors
One sensor per zone. Each sensor is mounted to the north facing wall and is modeled as a Quantum equipment. Each sensor equipment has three associated components, one for each of the three air properties being sensed: dry bulb temperature, dew point temperature, and relative humidity.
Weather Data
Chicago, IL
Mechanical Equipment
None
Customer Warehouse 2 in Atlanta
ATTRIBUTE
DESCRIPTION
Location
Atlanta, GA
Size
Roughly 253,000 square feet
Description
The warehouse building has an L-Shaped design, with goods designed to flow from one end of the L-shaped leg to the end of the other leg. The building is partitioned into six spaces. The Inbound Loading, Receiving, Shipping, and Outbound Loading zones are approximately equal in size. Inbound Unloading and Outbound Loading zones have dock doors on their end walls to receive and dispatch goods from and into the trailers. There are three vehicle access doors in all out of which two are located on the south wall of the storage space whereas the other one is on the east wall of the storage space.
Floor to Ceiling Height
18 feet in offices; 32 feet in warehouse.
Time-series Data Available
For 2021. Values are stored using SI units.
Zone Sensors
One sensor per zone. Each sensor is mounted to the north facing wall and is modeled as a Quantum equipment. Each sensor equipment has three associated components, one for each of the three air properties being sensed: dry bulb temperature, dew point temperature, and relative humidity.
Weather Data
Atlanta, GA
Mechanical Equipment
None
