It may not be applicable to most building applications, but for electrical sensors it's desirable to have tags to split out voltage/current magnitude and angle. This is especially true for customers that want to understand their site power factor and/or examine options for power factor correction (e.g. to avoid a power factor penalty charge). More applicable to industry than commercial facilities, but anyway.

Here are a few possible ways this could be done.

1. Add an angle tag:

   volt angle sensor
   volt phase angle sensor
   current angle sensor
   current phase angle sensor

2. Or, add an angle tag and add an optional magnitude (or mag?) tag to disambiguate when both measurements are present:

   volt magnitude sensor
   volt angle sensor
   volt phase magnitude sensor
   volt phase angle sensor
   current magnitude sensor
   current angle sensor
   current phase magnitude sensor
   current phase angle sensor

3. Or, to completely avoid ambiguity and conflicts with existing tags, add tags voltAngle and currentAngle:

   voltAngle sensor
   voltAngle phase sensor
   currentAngle sensor
   currentAngle  phase sensor

Of these, I like option #2 the best: add both magnitude and angle tags which can apply to voltage or current, but state that in the absence of either tag, the measurement is assumed to be a magnitude measurement. In my opinion, this is the cleanest and most extensible option.

Valid units for angles are deg and rad, both already defined in the Haystack standard. (Although I'd like to see ° as an acceptable alias for deg.)

I am not all familiar with angle versus magnitude, so just to confirm - what we are currently calling volt phase=X sensor is the magnitude right?

What what example is angle? Is there more than one angle point for different angle values?

I am not all familiar with angle versus magnitude, so just to confirm - what we are currently calling volt phase=X sensor is the magnitude right?

Yes. The angle/magnitude distinction gets into the mathematical treatment of AC waveforms: an AC voltage or current is represented by a magnitude and an angle. E.G. if

M * sin (w*t + phi)

defines an AC voltage, M is the magnitude and phi is the phase angle, or "phase shift", with respect to a reference waveform (typically, for buildings, the phase A voltage at the electric grid interconnection). The phase angle difference between voltage and current is, in part, what defines the power factor. More info here.

Usually when we measure voltage in buildings we report the magnitude only. Magnitude is more relevant and easy to measure; angle is harder because you need a reference. Typically, you only get angle measurements out of expensive power quality meters.

What what example is angle? Is there more than one angle point for different angle values?

Each voltage and current magnitude (phase A, B, and C) has an associated angle. For three-phase systems, the phase A, B, and C angles should each be approximately 120deg apart (e.g. 0, 120, and 240). Average angle is a relatively meaningless quantity, but leaving the phase tag off is still useful for single-phase systems.

I think the voltAngle-style solution (above) above would be the best to go with. This avoids a breaking change with the existing volt tag in addition to not creating confusion for those who would not need/use the angle tag.

Also, I don't know that "magnitude" is the best way to describe this value. I agree that if we are discussing the system as a vector plot, the term "magnitude" would be used. However, in general, "magnitude" would apply to a number of measurements. In the case of voltage, I think we could refer to the magnitude as potential (if needed) and with electrical current, the existing tag current should suffice.

This topic does bring up a question. When we made the kw to power shift, should we have changed volt to potential or elecPotential (It would have been a similar shift from a tag that is the same as the units)? This is just a thought and not a proposal. It would help in this situation since we would be talking about angle of the potential instead of try to separate these concepts.

Should we include data about the reference of the angles? Meters put out "angle" measurements for voltage/current/phase/etc but what this value doesn’t state is the reference. An angle is a measurement between two vectors, but in this discussion we are only discussing the angle of one vector. The reference vector is being assumed. In a lot of meters, the reference vector that everything else is measured from is the phase A voltage. Do we adopt this as a standard or just let the meter decide what the reference is? How would we handle a meter that uses a different reference? Does this even matter to an end-user or can we just accept the value as presented?

I agree that the magnitude vs. angle terminology comes out of the electrical engineering power systems domain, but it is the most consistent with industry terms of art. In addition, it is the most consistent with the underlying mathematical concepts of AC waveform measurement. I would therefore advise against using a more ambiguous term such as potential to describe the magnitude.

Other thoughts:

• Voltage and current are terms of art for actual physical quantities in addition to Volts being a unit, so I personally think volt and current are still the clearest and most appropriate tags.
• Currents have angles too, so whatever solution is adopted should work with the current tag in some way. currentAngle would work, but of the solution options I proposed I actually like voltAngle and currentAngle the least because they involve compound tags that can actually be separated into distinct concepts (like elecMeter to elec meter). The main argument for compound tags is to avoid breaking changes, but that can be accomplished in other ways as well.
• While it is true that self-contained power meters (as opposed to phasor measurement units) do use only a local angle reference (e.g. phase A voltage), in practice the reference angle of phase A will differ very little within a single site, and can be considered the same reference for practical purposes. (This is akin to measuring voltage between hot and neutral at different places in the building network: technically the potential of the neutral reference may be slightly different in different locations, but in practice the differences are negligibly small.)

The existing usage of volt can be defined as the magnitude of electric potential (with the unit:”V”). In fact, in the units.txt we already have voltage grouped under "electric potential". We have other units that could also have an associated magnitude, such as force. If we were to go with volt magnitude, it would both break from our existing usage of volt and set us up for a possible additional change down the road in the event someone would like to model force with magnitude and direction.

I agree that we should not set about using compound words for tags as a general rule. However, with the proposed options, that seemed like the best solution.

*

This next idea, which could potentially be a separate proposal, would be to add functionality surrounding the concept of units. This functionality would allow a unit to be interrogated and return the unit type:

unit->type

where
(unit:"V")->type 
would return "electric potential" 

This is just an illustration of a concept.  I understand that this syntax
would probably not be workable.

There would be several things that would need to change for this concept to be implemented but it would help in this situation. We have several tags that describe the type of units used (i.e. press) but if the point is tagged with the units, why can't we use the units to fill in the blank to get "pressure", "angle", "electric potential", etc? We would probably want to revisit the naming of the unit groupings and breakout the "dimensionless" grouping into more functional groups. I would also foresee significant programming changes to incorporate this idea. This would be a significant undertaking to do it well but I think it would have great advantages in the long run.

*

Another distinction that we need to make while we are on the topic of angles is direction of the angle. As I stated above, if we are looking at the angle of a specific voltage or current, the measurement is most likely referenced to the phase A voltage (0 deg) and all other values would fall into the range of 0-360deg (assuming that the units of the angle are in degrees).

However, these are not the angles that people tend to care about in this domain. Instead, as in the first paragraph of this topic, we want to know about angles as they relate to power factor. Power factor can be expressed as the cosine of the angle between the current and voltage of a phase. (more info on this topic). What power factor doesn't tell you (or at least I haven't seen a meter that reports power factor in this manner), and what would be necessary to correct a power factor issue from a directional standpoint, is the direction of the angle between voltage and current. This is generally expressed with power factor in the terms leading or lagging. These terms describe the angle of the current with respect to the voltage (the current is leading/lagging the voltage). Typically a utility will charge you below a certain threshold on a lagging power factor and charge you for any leading power factor.

We can go into great depth on why buildings typically have a lagging power factor and why generators are designed for this load but I don't know that it is necessary here. I think what we want to do is describe how we want to model the phase angle between voltage and current. By convention, a lagging current is expressed as angle shifting from the voltage in a positive direction (0 -> 5deg). A leading angle can be expressed in one of two ways. For example, a leading angle may be described as -4deg or 356deg. A phase angle of +30deg or -30deg (or even 330deg) would produce the same power factor but be corrected in different manners.

I would recommend that we go with the +/- format with respect to voltage/current phase angle measurements for rapid human readability and graphing purposes. If we used a constantly positive angle (i.e. 4 deg -> 356deg), the resulting graph would be a spike in power factor angle instead of a showing that the power factor shifted directions.

Good points. Some quick thoughts...

• I would argue that there's no actual conflict in adding a magnitude tag (or similar) to disambiguate from angle provided that magnitude is assumed in the case that no disambiguating tag is present. (Option 2 in original proposal, with modification to specify default.) There is some precedent for this, e.g. "cov" versus "linear" for the hisInterpolate type.
• I like the concept of interrogating units for their type, but I agree it's a separate discussion.
• What the bounds are on angle measurements is also a separate discussion and not necessarily tied to the tagging. I tend to use +/-180deg as the sweep. If zero is the reference, this gives you 0, +120, and -120 as the nominal voltage phase angles, and the phase current angles are also unlikely to cross the 180deg boundary (unless your power factor is really terrible). However, in practice you are pretty much stuck with whatever your power quality meter is reading. What this points to, though, is the need to use modulo arithmetic in calculations related to phase angle (typically handled in power systems software by computing using complex numbers, but that's almost certainly out of scope for Haystack).

I think this thread needs some input from others before any decisions are made. Maybe this is too esoteric a topic to include dedicated tags for?