Redefining Setpoint Classifications: Target and Threshold about brick

[JoelBender]

I like the additional refinement, even though I prefer a shallow hierarchy rather than a deeper one, and the new names are better.

I think of deadband as an additional parameter to a threshold calculation, so in the case where a deadband is manipulated to allow for "tight" or "loose" control there might be some additional range that the deadband is expected to vary between, but is there going to be an alarm when the deadband exceeds some value?

I thought Time Setpoints where things like minimum/maximum on/off time, but looking at the version 1.3 hierarchy they are something different.

[connorjcantrell]

Hi @gtfierro,

I'd like to move forward with this PR, but want to get your feedback first. Here are a few options we could consider:

1. Add additional parents to each Setpoint

In this approach, we would avoid restructuring existing class hierarchies and add one of the following classes as a parent:

• Target Setpoint
• Upper Threshold Setpoint
• Lower Threshold Setpoint

setpoints = {
    "Setpoint": {
        "subclasses": {
            "Target_Setpoint": {},
            "Threshold_Setpoint": {
                "subclasses": {
                    "Upper_Threshold_Setpoint": {},   
                    "Lower_Threshold_Setpoint": {},
                }
            },
            "Pressure_Setpoint": {
                BRICK.hasQuantity: BRICK.Pressure,
                "parents": [
                    BRICK.Target_Setpoint,
                ],
                "subclasses": {}
            },
            "Cooling_Temperature_Setpoint": {
                BRICK.hasQuantity: BRICK.Temperature,
                "tags": [TAG.Point, TAG.Temperature, TAG.Setpoint, TAG.Cool],
                "parents": [
                    BRICK.Upper_Threshold_Setpoint,
                ],
                "subclasses": {}
            },
            "Heating_Temperature_Setpoint": {
                BRICK.hasQuantity: BRICK.Temperature,
                "tags": [TAG.Point, TAG.Temperature, TAG.Setpoint, TAG.Heat],
                "parents": [
                    BRICK.Lower_Threshold_Setpoint,
                ],
                "subclasses": {},
            },
            # etc.
        }
    }
}

2. Add a new tag to each Setpoint

setpoints = {
        "subclasses": {
            "Pressure_Setpoint": {
                BRICK.hasQuantity: BRICK.Pressure,
                 "tags": [TAG.Target, TAG.Pressure, TAG.Setpoint],
                "subclasses": {}
            },
            "Cooling_Temperature_Setpoint": {
                BRICK.hasQuantity: BRICK.Temperature,
                "tags": [TAG.Upper_Threshold, TAG.Point, TAG.Temperature, TAG.Setpoint, TAG.Cool],
                "subclasses": {}
            },
            "Heating_Temperature_Setpoint": {
                BRICK.hasQuantity: BRICK.Temperature,
                "tags": [TAG.Lower_Threshold, TAG.Point, TAG.Temperature, TAG.Setpoint, TAG.Heat],
                "subclasses": {},
            },
            # etc.
        }
    }
}

3. Restructure class hierarchy (Preferred)

Existing class hierarchies are altered, but nearly all class names remain. (See notes below)

Though this approach requires the most changes, it addresses the issue of incorrect semantics by clearly defining each class within its respective Setpoint type. This eliminates ambiguity and ensures that each class accurately represents its intended function.

.
├── target_setpoint
│   ├── pressure_setpoint
│   ├── humidity_setpoint
│   ├── temperature_setpoint
│   └── ...
└── threshold_setpoint
    ├── lower_threshold_setpoint
    │   ├── heating_setpoint
    │   ├── humidification_setpoint
    │   └── ...
    └── upper_threshold_setpoint
        ├── co2_setpoint
        ├── cooling_setpoint
        ├── dehumidification_setpoint
        └── ...

Some superclasses such as Temperature_Setpoint currently contain both Target and Threshold Setpoints. I propose repurposing Temperature Setpoint to be exclusively for "(Target) Temperature Setpoints". Alternatively, we could deprecate Temperature_Setpoint and replace it with Target_Temperature_Setpoint.

cc @jbkoh

[gtfierro]

Options 1 and 3 feel like duals. They both organize the setpoints along 2 dimensions: by quantity (e.g., Temperature) and by the setpoint type (e.g., Threshold). The difference between them is whether we organize the Python files by quantity or by setpoint type. Do I understand this right?

[connorjcantrell]

Option 1 adds new parent classes while keeping the existing hierarchy. This means some classes will still have mixed setpoint types as subclasses (e.g., Zone Air Temperature Setpoint has both target and threshold subclasses). For example, Zone Air Temperature Setpoint currently has the following subclasses:

• Zone Air Temperature Setpoint (Target?)
  • Effective_Zone_Air_Temperature_Setpoint (Target)
  • Occupied_Zone_Air_Temperature_Setpoint (Target)
  • Unoccupied_Zone_Air_Temperature_Setpoint (Target)
  • Zone_Air_Cooling_Temperature_Setpoint (Upper Threshold)
  • Zone_Air_Heating_Temperature_Setpoint (Lower Threshold)

Option 3 completely reorganizes the hierarchy, grouping classes by setpoint type first (target, lower threshold, upper threshold), then by quantity (temperature, pressure, etc.). This ensures all superclasses share the same setpoint type. Continuing with the previous example, it would look something like this:

.
├── lower_threshold_setpoint
│   └── lower_threshold_temperature_setpoint
│       └── heating_temperature_setpoint
│           └── air_heating_temperature_setpoint
│               └── zone_air_heating_temperature_setpoint
├── target_setpoint
│   └── target_temperature_setpoint
│       └── target_air_temperature_setpoint
│           └── target_zone_air_temperature_setpoint
│               ├── effective_zone_air_temperature_setpoint
│               ├── occupied_zone_air_temperature_setpoint
│               └── unoccupied_zone_air_temperature_setpoint
└── upper_threshold_setpoint
    └── upper_threshold_temperature_setpoint
        └── cooling_temperature_setpoint
            └── air_cooling_temperature_setpoint
                └── zone_air_cooling_temperature_setpoint

The primary focus with Option 3 is to prioritize setpoint type (target, upper threshold, lower threshold) over the when (i.e. Occupied, Unoccupied), substance (i.e. Air, Water), and measurement (i.e. Temperature, Pressure).

[connorjcantrell]

This issue has served its purpose in guiding the implementation of the setpoint-restructure PR