There are two big issues remaining to finish Haystack 4.  The first is finalizing all the ref tags and the second is finalizing the proposed query language enhancements.  This post contains a proposal for the first issue.  

There are two fundamental types of relationship ref tags defined by project haystack:

• "containment" tags: siteRef, equipRef, spaceRef
• "flow" tags: ahuRef, elecMeterLoadRef, chilledWaterPlantRef, etc

We have formalized the semantics of siteRef, equipRef, and spaceRef to strictly imply containment - this works well.

The other ref tags need to be re-evaluated.  Over the course of WG 551 we discussed different approaches for how to model these relationships:

1. Today we reference a specific entity type:

  chilledWaterPlantRef: @cwp

2. Use an extremely generic tag with nested data 
in the instance such:
 
  supplyRef: {chilled water ref:@cwp}

3. Use a more generic ref tag based on what is 
supplied, but not specific to the entity type which 
does the supplying:

  chilledWaterSupplyRef: @cwp

The current design (option 1) suffers from numerous problems:

• it explodes ref types
• its not very flexible since many different entity types might supply a given substance

Option 2 is a radical change from how things are done today.  And while it offers more flexibility, it probably moves too much of the semantics from defs into instances.

I'm going to propose that we standardize option 3 using a convention that all "flow" relationships are formatted as "{foo}SupplyRef". These tags are always applied to the entity on the receiving end of the relationship.  Note that with proposed relationship queries it will still be possible to query from either side of the relationship.

The following tags would use the new design:

 Haystack 3            Haystack 4
 ----------            -----------
 ahuRef                airSupplyRef
 chilledWaterPlantRef  chilledWaterSupplyRef
 hotWaterPlantRef      hotWaterSupplyRef
 steamPlantRef         steamSupplyRef
 elecMeterLoad         elecSupplyRef
 steamMeterLoad        steamSupplyRef
 gasMeterLoad          gasSupplyRef

Note that although it's a breaking change, there are no naming conflicts.  So you can continue to use both the old tags and new tags side-by-side, making transition relatively easy.  We could use a more generic term such as "inputs", which would make more sense for meter-to-load relationships.  But for most use cases I think the term "supply" is more intuitive and the term of art.

Here are examples of a couple defs:

  def: ^airSupplyRef
  is: ^ref
  of: ^???
  receives: ^air  // implies that we receive air from referent

  def: ^chilledWaterSupplyRef
  is: ^ref
  of: ^???
  receives: ^chilled-water

  def: ^elecSupplyRef
  is: ^ref
  of: ^???
  receives: ^elec

So far everything is pretty straight forward.  However, the big question is what should the of tag of these refs point to?  In the case of ahuRef it was simple, it points to an ahu.  This makes things pretty simple for tooling, because you just open an entity picker for things tagged ahu.

Now we require a design that is more abstract.  For example airSupplyRef can point to anything that "supplies air", steamSupplyRef points to anything that "supplies steam", etc.  Here are some ideas:

Option 1: try to figure out something with conduits. In reality, almost all of these flow/connections/relationships are made via a wire, duct, or pipe.  The main problem with this approach is that it's very detail oriented, and in most models people aren't going to model the individual ducts and pipes.  I like this approach, but have not come up with anything pragmatic in this direction.

Option 2: add some new tag onto everything that is a potential supplier.  For example you would add the airSupply tag to an AHU entity, elecSupply tag to an generator, meter, or battery.  This keeps tooling simple because it continues to let pickers be strictly instance tag based.  However, it is awkward and unnecessary to require that information be annotated on a per instance basis.

Option 3: annotate equipment in the defs that they are potential suppliers.  This seems like the most pragmatic solution.  It does require tool vendors to add def indirection to their entity pickers.  But it avoids a lot of boiler plates tags in instance data.  

If you agree that option 3 is best, then the next question is what design pattern should be used?  One simple mechanism would be to re-purpose the supplies and receives tags to also be used in equip:

def: ^ahu
is: ^equip
supplies: ^air

The problem with this approach is that the tags receives and supplies would be doing dual duty because they already have very strict semantics as being relationship tags (used only on refs).  And to make this work, I think need to use subtyping.  So I'm going to propose the noun term "supply":

def: ^supply
---
def: ^air-supply
is: ^supply
---
def: ^ahu
is: ^equip, ^air-supply
---
def: ^airSupplyRef
is: ^ref
receives: ^air
of: ^air-supply

There some other directions we could go too - maybe trying to model all the inputs and outputs for a given equipment. For example there are outputs to a process such as exhaust which are not necessarily a "supply". But sticking with receive/supply seems to be the simple design that solves the 90% use case.

Thoughts?

Thanks for this fantastic write-up, Brian. I have the following questions/comments:

1. In the first list of options, I like option 2 or 3. I lean toward Option 2, as it matches the existing standard well and seems the only solution generic enough to solve to the type-explosion issue. However, with your examples, I think Option 3 is could be a reasonable middle-ground.
2. Couldn't the xSupplyRef still suffer from some type-explosion on the phenomenon? For example, condenserWaterSupplyRef, makeupWaterSupplyRef, and hotDeckAirSupplyRef. Where would we draw the line on how specific to be on the phenomenon?
3. gasSupplyRef should probably be naturalGasSupplyRef
4. Assuming we go with Option 3 in the first set, in the second list of options, I prefer Option 3.
5. I think the supply def works well, but is a bit confusing with our existing use of supplies and conventional use of supply air/water as opposed to return or exhaust. For that reason, it might be worth considering the following:
   1. Changing xSupplyRef to xDeliveryRef, xProvideRef, or xConveyedFromRef. Also change supply to delivers, or provides
   2. Alternatively, supplies/receives for Refs could be changed to something else
6. Could we allow one-to-many relationships within the Ref system? For example, could the airSupplyRef tag support a value of a list of Refs? This would allow users to model equipment explicitly as performing in series or parallel configurations.

Thanks, Brian. This is some really awesome stuff.

Thanks for feedback Jay...

2 Couldn't the xSupplyRef still suffer from some type-explosion on the phenomenon?

It does define quite a few tags. However, there is a fairly finite amount of substances that are conveyed between equip compared to all the different equipment types. There is a total 20 subtypes of substances, but a total of 62 subtypes of equip. And I think the number of equip subtypes will grow more quickly over time.

3 gasSupplyRef should probably be naturalGasSupplyRef

We have been using gas for tags related to naturalGas such as gasHeating. And likewise oil for fuelOil such as oilHeating. I don't think there is much chance for confusion or collision in those cases, but I don't have a strong preference if everyone wants to change those tags to naturalGasHeating and fuelOilHeating?

5 I think the supply def works well, but is a bit confusing with our existing use of supplies and conventional

I personally don't have any preferences as long as its consistent. In HVAC "supply" seems to be the term of art for the conveyance air, water, and steam. But a more generic term would probably work better if we can coin one. This is definitely a topic where people should speak up!

6 Alternatively, supplies/receives for Refs could be changed to something else Could we allow one-to-many relationships within the Ref system?

We already made this change and said in cases where you really have multiple that you can use a list of Refs. The filter syntax has been enhanced to match if any one item in the list matches. Although I think we need some best practices and experience with this approach before we take it too far.

So I decided this is a good topic on which to jump back into the Haystack 4 discussion! I agree with Jay; thank you for the detailed proposal.

On your options, I like Option 3 -> Option 3 best. (Option 3.3?) This seems to be the one you're leaning toward as well, but it does need kinks worked out.

I may not be fully understanding the issue with using supplies and receives as def tags on the equipment definitions. With contains and containedBy, the referent is the object that does the containing (or is contained). With supplies and receives, is the problem that they're referents are supposed to be physical quantities? In that case, I agree with some new tags possibly being needed.

supply suffers in that there's not an obvious counterpart to describe the other end of the link. (source also suffers that problem.) Here are some noun options for the two entities on either side of a flow:

• origin / destination
• producer / consumer
• upstream / downstream?

I guess these would be used in the defs only? In the way that you proposed to use supply above?

For another point of reference, have a look at Brick's relationship model: https://brickschema.org/ontology/1.1/#Relationships

Brick models the following:

• Flows: feeds / isFedBy
• Control: controls / isControlledBy (also regulates / isRegulatedBy)
• Measurement: measures / isMeasuredBy

feeds / isFedBy (or just fedBy) is a logical counterpart to contains / containedBy. Maybe we can use these for the equip relationships and reserve supplies and receives for the quantities.

def: ^vav
is: ^air-destination
fedBy: ^air-origin
...
---
def: ^ahu
is: ^air-origin
feeds: ^air-destination
...
---
def: ^airSupplyRef
is: ^ref
receives: ^air
of: ^air-origin

Other:

• There's also Jay's point about whether "Supply" is the correct word to use in xSupplyRef. In this context, "Supply", "Source", "Feed", "Origin" all seem ok, but none seems perfect in all circumstances. I'm not sure it matters all that much, though.
• I like gas = natural gas and oil = fuel oil the way they are (for brevity), but I can see the argument for making them more precise.

There's also Jay's point about whether "Supply" is the correct word to use in xSupplyRef.

I'm actually thinking maybe we don't use any term like "supply" in the ref tags and just use the substance you are receiving:

airRef
steamRef
elecRef
chilledWaterRef
...

Those tags would still have the relationship semantics to mean supplied by the referent. But it would also be easier in the future to apply new terminology to those tags if supply didn't quite make sense.

That is also a little more consistent with siteRef, equipRef which means contained by site, equip, etc.

Any disagreement with that vs supplyAirRef, supplySteamRef, supplyElecRef?

I like gas = natural gas and oil = fuel oil the way they are (for brevity), but I can see the argument for making them more precise.

One vote for keeping the short names, anyone else?

I'm actually thinking maybe we don't use any term like "supply" in the ref tags and just use the substance you are receiving... That is also a little more consistent with siteRef, equipRef which means contained by site, equip, etc.

I could live with that. Interested to see other opinions.

I'm actually thinking maybe we don't use any term like "supply" in the ref tags and just use the substance you are receiving

I think that's a good solution.

I like gas = natural gas and oil = fuel oil the way they are (for brevity), but I can see the argument for making them more precise.

Sorry, I didn't really explain my reasoning here: I just suggested naturalGasRef over gasRef because gas and naturalGas are both phenomenon definitions. If our typical format is going to be <phenomenon>Ref, then shortening naturalGas to gas has potential to cause confusion and future tag conflicts.

At the end of the day though, it's not a big sticking point for me.

In general - I like this discussion and am hoping this can maybe turn into a working group to flesh out? Thanks for starting Brian and looking forward continuing.

There are two fundamental types of relationship ref tags defined by project haystack: "containment" tags: siteRef, equipRef, spaceRef "flow" tags: ahuRef, elecMeterLoadRef, chilledWaterPlantRef, etc

A use case that seems to frequently come up is how to support asset management type applications, where knowing where a thing is located in physical space is necessary. Maybe this is covered by "containment", but it's unclear to me and I think is a good use case to keep document / make sure we have clarity on how to implement. Would also like to bring the concept of UBID into this discussion as I think it is becoming relevant.

Chat soon!

If our typical format is going to be <phenomenon>Ref, then shortening naturalGas to gas has potential to cause confusion and future tag conflicts.

We already changed these tags from gasHeat to gasHeating, so its already a breaking change. And you are right its probably better to be more specific and consistent. For next rev I will change that to naturalGasHeating and fuelOilHeating. And we will use the longer name for the ref tags ie naturalGasRef.

Maybe this is covered by "containment", but it's unclear to me

Its covered by the spaceRef tag which indicates where an equip is physically located. We have not currently added geoCoord as a tag to space (its only on site), but we could certainly do that if people thought it was useful.

So current proposal is that "flow" relationships will be modeled with a ref tag on the receiver entity to refer to the supplier entity using the convention <phenomenon>Ref:

• airRef
• elecRef (or should it be acElecRef?)
• naturalGasRef
• chilledWaterRef, etc
• steamRef

I just suggested naturalGasRef over gasRef because gas and naturalGas are both phenomenon definitions.

This is a good point.

We have not currently added geoCoord as a tag to space (its only on site), but we could certainly do that if people thought it was useful.

This is a separate (and complicated!) discussion, I think. Currently geoCoord is defined as "Geographic coordinate in latitude/longitude formatted as C(lat,lng)". To be truly useful within a building, it needs to be generalized to apply to either 2D or 3D space, to support more than just latitude/longitude, and potentially to support a standard reference. Then there's a discussion of how to combine coordinates to define 2D or 3D polygons to define spaces. There could easily be an entire working group around just this topic.

elecRef (or should it be acElecRef?)

Hmm. The reason to use acElecRef would be to also define dcElecRef assuming you have a dual-source device. However, that situation isn't unique to electricity. Consider:

• Dual duct VAV units >> Multiple airRefs
• Generator automatic transfer switches >> Multiple elecRefs (or acElecRefs)
• Anything that uses hot and chilled water >> Multiple waterRefs (i.e. chilledWaterRef, hotWaterRef)

I guess with water, we are already down the path of chilledWaterRef, hotWaterRef, domesticWaterRef? Would we also want to optionally subclass elecRef and airRef with similar structure? (Note that the more we use compound tags for refs to do this, the more we are getting back into the "you must know exact word order" territory that has always make compound tags problematic, although the generalized relationship queries do help you get around that.)

I suppose a generally reasonable way to handle this is to support <phenomenon>Ref for all reasonable levels of the phenomenon tree, and build them out together with the same canonical tag order as the phenomenon compound tags. Then you would want to issue guidance to use most precise reference tag that fully disambiguates the ref for your equipment? I think for single-duct VAV units and single-source AC-connected equipment, there's no need to be more precise than airRef and elecRef.

Hmm. The reason to use acElecRef would be to also define dcElecRef assuming you have a dual-source device

I suggested it because we now have ac-elec and dc-elec as two different subtypes of electricity. Consider a given equip knows what it needs and is supposed to be hooked up to an A/C or D/C source, its probably better to use acElecRef. Although at the same time its kind of awkward since 90% of everything is A/C that we are working with. So I'd probably just stick with elecRef myself

Dual duct VAV units >> Multiple airRefs

We established this convention already during the WG sessions that you will just use airRef with a list of refs and the query language handles it (== will match anything in the list)

I'm +1 for tags airRef, chilledWaterRef, etc?

This is a fantastic discussion, and I’m excited to see the direction it's going. To me, this could help connect the dots between Haystack, energy modelling, BIM, and graphics.

Ideally this relationship definition could support both very detailed modelling of equipment relationships down to the wire, duct, pipe level (for ex. model all components inside an AHU and their relationship and order relative to each other) but also work for simplistic modelling of high level equipment connections (i.e air handler to air terminal unit)

With that in mind, I propose the following:

1. Instead of supplies or <phenomenon>ref, what about something like, connectsTo/ connectsFrom? That way the direction of flow is somewhat more implicit in the tag without carrying the connotations of a word like "supplies".
2. To keep the relationship tag as concise as possible and preclude the need to have 1 ref tag for every phenomenon, perhaps the phenomenon (or instance of it?) could be passed in as a parameter or second object. I'm not sure if this is allowed in Haystack?

bringing it all together, it could looks something like this:

// hot water plant entity id: @hwp

// AHU entity which receives hot water from the plant above id: @ahu, connectsTo: @hwp, @hotwaterloop

or alternately: id: @ahu, connectsTo: @hwp, hot-water

I like the feedsTo/fedFrom that Brick uses, and I think it works perfectly as an implied relationship of the phenomenon that is being connected. If the @hwp connects the @hotwaterloop or hot-water to the @ahu, then it can be inferred that hot-water is fed from the plant to the ahu via the loop.

You can also start to model a full loop with inputs/outputs for each piece of equipment in order: @chiller connectsTo @pump connectsTo @coil connectsTo @chiller

The one drawback of this approach is that each connection of each separate phenomenon becomes a separate instance of connectsTo.

I'd also be glad to participate in a WG if this become formalized as such.

To keep the relationship tag as concise as possible and preclude the need to have 1 ref tag for every phenomenon, perhaps the phenomenon (or instance of it?) could be passed in as a parameter or second object

Haystack only allows simple name/value pairs - in that regard it is similar to RDF triples. While its possible to make the value a nested data structure, we've tried hard to avoid that - it was in my original post for the thread as 2 option:

supplyRef: {chilled water ref:@cwp}

feedsTo/fedFrom that Brick uses, and I think it works perfectly as an implied relationship of the phenomenon

Since you have lots of potential incoming and outgoing relationships it actually doesn't work that well without adding a extra structure or complexity into your model. For example given a AHU, its possible that it will have incoming chilled water, incoming hot water/steam, and an incoming electrical source. What we want to avoid is forcing people to model the actual ducts/wires in detail. So without requiring complicated inference about what is feeding what, the simplest thing to do is just embed the "what" into the tag name itself.

So I know that EnergyPlus uses the concepts of connections on an object, where the connection defines the phenomenon and directionality basically. So an AHU would expect hot water and chilled water as incoming connections, and air as an outgoing connection. Therefore, when I try to connect something like a terminal unit, which expects air as an incoming connection, it knows:

1. Whether the upstream object I'm trying to connect to is supplying the correct phenomenon (air).
2. What that thing then is (i.e. an ahu)

Could we do something where the query just becomes to try and find the thing that is supplying the defined phenomenon?

vav and supplyRef: air would return the entity supplying air, i.e. the AHU

vav and supplyRef: chilled-water would return a chiller or plant

etc. keeps it somewhat concise and generic?

Cory,

We already have a proposal to enhance the query syntax to query relationships exactly as you suggest...

This is how an AHU might be modeled today with current proposal:

id: @hwp hot water plant equip
id: @cwp chilled water plant equip
id: @meter elec meter equip
id: @ahu ahu equip hotWaterRef:@hwp chilledWaterRef:@cwp elecRef:@meter

There are always two "pieces" of a "connection" - what the connection means and what its connected too. In Haystack we want don't want to force people to create first class connection objects in their models. So that means that we want to capture the semantics in the tag name itself (the def of the ref tag):

// this defines hotWaterRef to mean I receive hot-water
// from the referent and that a tool should bind it only to
// things that subtype from hot-water-supplier
def: ^hotWaterRef
is: ^ref
of: ^hot-water-supplier
receives: ^hot-water

So per the existing query enhancements proposal:

// query anything that receives hot water
receives-hot-water?

// query only things that receive hot water from given plant
receives-hot-water? @hwp

// query only AHUs that receive hot water from given plant
ahu and receives-hot-water? @hwp

Note: that there has been some discussion on the syntax, so it will probably change. But that basic concepts appear to be solid.

Well, glad we're on the same page then... :) ... sorry lots of moving parts to try and keep track of.

I suppose a generally reasonable way to handle this is to support <phenomenon>Ref for all reasonable levels of the phenomenon tree, and build them out together with the same canonical tag order as the phenomenon compound tags. Then you would want to issue guidance to use most precise reference tag that fully disambiguates the ref for your equipment? I think for single-duct VAV units and single-source AC-connected equipment, there's no need to be more precise than airRef and elecRef.

+1 for this