add writing to schedules and EMS actuators to Spawn

[mwetter]

This issue is to add functionality to write the EnergyPlus schedules and EMS actuators.

See https://lbl-srg.github.io/soep/softwareArchitecture.html#sending-input-to-energyplus for specification.

The development branch issue1633_schedulesActuators is based on issue1129_energyPlus_zone

[mwetter]

If an input or output or an EMS actuator is not supported or present in EnergyPlus, then spawn must return a nonzero error code and write spawn.log file at the same location as the json configuration file is.

[kbenne]

I have added this feature in this commit: NREL/Spawn@a743b67

[kbenne]

This should be fully addressed with NREL/Spawn@26fd4ac

NREL/Spawn@a743b67 did not include explicit support for schedules (although you could use a general actuator to write the schedules, now there is support directly.

    "schedules": [      
       {                               
          "name"    : "BLDG_LIGHT_SCH",
          "unit"    : "1",      
          "fmiName" : "Lights_Schedule"
        }
     ]       ```

[mwetter]

The test file that @kbenne uses is:

{
  "version": "0.1",
  "EnergyPlus": {
    "idf": "RefBldgSmallOfficeNew2004_Chicago.idf",
    "weather": "USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw"
  },
  "fmu": {
      "name": "MyBuilding.fmu",
      "version": "2.0",
      "kind"   : "ME"
  },
  "model": {
    "zones": [
      { "name": "Core_ZN" }
    ],
    "outputVariables": [
      {
        "name":    "Zone Mean Air Temperature",
        "key":     "Core_ZN",
        "fmiName": "Zone_Temperature"
      },
      {
        "name":    "Site Outdoor Air Drybulb Temperature",
        "key":     "Environment",
        "fmiName": "Outside_Temperature"
      },
      {
        "name":    "People Occupant Count",
        "key":     "Core_ZN People",
        "fmiName": "Core_Zone_People_Output"
      },
      {
        "name":    "Lights Electric Power",
        "key":     "Core_ZN_Lights",
        "fmiName": "Core_Zone_Lights_Output"
      }
    ],
    "emsActuators": [
      {
        "variableName"  : "Core_ZN People",
        "componentType" : "People",
        "controlType"   : "Number of People",
        "unit"          : "1",
        "fmiName"       : "Core_Zone_People"
      }
    ],
 		"schedules": [
       {
        	"name"    : "BLDG_LIGHT_SCH",
        	"unit"    : "1",
        	"fmiName" : "Lights_Schedule"
        }
     ]
		}
} 

[mwetter]

@kbenne : I suggest for the next build, you rename

"variableName"  : "Core_ZN People",

to

"name"  : "Core_ZN People",

unless you have a reason to deviate from using name as the key as is used for all other objects.

[mwetter]

@kbenne : EMSActuators have in https://lbl-srg.github.io/soep/softwareArchitecture.html#actuators and in the idd file four fields:

EnergyManagementSystem:Actuator,
       \memo Hardware portion of EMS used to set up actuators in the model
       \min-fields 4
  A1 , \field Name
       \required-field
       \type alpha
       \note This name becomes a variable for use in Erl programs
       \note no spaces or other special characters (-,+,/,\) allowed in name
  A2 , \field Actuated Component Unique Name
       \required-field
       \type alpha
  A3 , \field Actuated Component Type
       \required-field
       \type alpha
  A4 ; \field Actuated Component Control Type
       \required-field
       \type alpha

but your snippet of the json file only has three fields. Is this a bug in the json file, or if not, is your variableName corresponding to A1 or A2?

[mwetter]

@kbenne : Can you please clarify #1633 (comment)

[kbenne]

variableName is equivalent in meaning to field A2. That is to say that variableName is the actuated component unique name. If you are trying to actuate a "ElectricEquipment" object in EnergyPlus which ElectricEquipment idf object are you actuating.

I would be fine with calling variableName just "name".

In spawn there is no direct equivalent to field A1 which is used to reference the given actuator throughout EMS programs. The closest analog is the fmiName.

EnergyManagementSystem:Actuator,
       \memo Hardware portion of EMS used to set up actuators in the model
       \min-fields 4
  A1 , \field Name      !  -> closest equivalent is fmiName
       \required-field
       \type alpha
       \note This name becomes a variable for use in Erl programs
       \note no spaces or other special characters (-,+,/,\) allowed in name
  A2 , \field Actuated Component Unique Name          ! -> variableName
       \required-field
       \type alpha
  A3 , \field Actuated Component Type                 ! -> componentType
       \required-field
       \type alpha
  A4 ; \field Actuated Component Control Type.  ! -> controlType
       \required-field
       \type alpha

[mwetter]

@kbenne : If A1 is used to reference the given actuator throughout EMS programs, then we should allow in Spawn to reference this name, no? A use case is that a user provides an idf name, which uses A1 in EMS programs, and now this user wants to change the value of this variable through Spawn. Wouldn't E+ then require A1 to be the name used in the idf, and hence Spawn needs to send A1.
Per https://lbl-srg.github.io/soep/softwareArchitecture.html#actuators, "No entry in the idf file is required to write to an EMS actuator." so this is the only place where A1 can be received.

I think what is confusing here is that EnergyManagementSystem:Actuator can change an EMS variable value through A1, in which case A2 to A4 are not used, or it can change a components value through A2, in which case A1 is not used. Is this correct?

[kbenne]

If someone wants to interact with a given actuator through EMS in the idf file, then they need to insert the EnergyManagementSystem:Actuator idf object themselves. They need to identify the idf object they want to actuate by the name, type, and control type. Ie "My Favorite Lighting Schedule", "Schedule Compact", "Schedule Value". They use the name field given in the "EnergyManagementSystem:Actuator" idf object to refer to that actuator in EMS programs.

To actuate that same thing in spawn you must provide those three identifying values, "My Favorite Lighting Schedule", "Schedule Compact", "Schedule Value", however the name that you use to refer to that FMU variable does not need to be the same or even correspond to the name of an EnergyManagementSystem:Actuator object (field A1).

I believe it is technically possible to actuate a given thing from both an EMS program and the FMU. I have been designing to allow for that at least in the future. The calling points come into play here. In EMS you have control over the calling point, whereas actuating via the FMU you don't. That said FMU is synchronized at the highest frequency therefore FMU actuations will have priority. I want to emphasize technically possible, and in the future. Currently I am actively filtering a limited set of the supported idd types, and EMS programs are currently filtered out. The idea would be to expand the supported set over time.

[mwetter]

@kbenne : So the statement

No entry in the idf file is required to write to an EMS actuator.
need to be removed from the design contract at https://lbl-srg.github.io/soep/softwareArchitecture.html#actuators?

Similarly, what is the intention for schedules? I thought we also said they need not be in the idf file, but simulating Buildings.ThermalZones.EnergyPlus.Validation.Schedule.OneZoneEquipmentScheduleNonSampled after removing the schedule from the idf file leads to

Failed to find variable OneZoneEquipmentScheduleNonSampled.schInt:INTERMITTENT in /home/mwetter/proj/ldrd/bie/modeling/github/lbl-srg/modelica-buildings/Buildings/tmp-simulation-OneZoneEquipmentScheduleNonSampled.building/OneZoneEquipmentScheduleNonSampled.building.fmu. Make sure it exists in /home/mwetter/proj/ldrd/bie/modeling/github/lbl-srg/modelica-buildings/Buildings/Resources/Data/ThermalZones/EnergyPlus/Validation/SingleFamilyHouse_TwoSpeed_ZoneAirBalance/SingleFamilyHouse_TwoSpeed_ZoneAirBalance.idf.
The stack of functions is:
Buildings.ThermalZones.EnergyPlus.BaseClasses.zoneInitialize
Buildings.ThermalZones.EnergyPlus.BaseClasses.zoneInitialize(
zon.fmuZon.adapter, 
time)
Error: Integrator failed to start model.
fmi2Terminate returned with non-OK status for building OneZoneEquipmentScheduleNonSampled.building

I would expect this to either work, or that EnergyPlus returns an error message saying that this schedule need to be instantiated in the idf file. The current behavior of writing the fmu and then telling the user that the schedule is not in the fmu won't help for most users.

Please add such tests in the EnergyPlus code so we can give more meaningful instructions, and let me know if schedules (and actuators) need to be instantiated in idf.

[kbenne]

I think "No entry in the idf file is required to write to an EMS actuator" is a true statement. That was the point I think I must have failed to communicate.

"If someone wants to interact with a given actuator through EMS in the idf file, then they need to insert the EnergyManagementSystem:Actuator idf object themselves."

This is also true, but spawn is not EMS and therefore there is no requirement for idf input such as EnergyManagementSystem:Actuator. In Spawn we write to actuators through the EnergyPlus API as we wish. This is also true for python extensions that have recently been introduced to EnergyPlus.

For schedules, we need a schedule object in the idf file, but I don't think any other objects such as EnergyManagementSystem:Actuator to actually actuate or otherwise change a schedule's value. I suppose I can inject a missing schedule into the idf if the spawn input file requests to actuate a schedule that does not exist. I'm not clear on the use case though, because something in the idf file would need to reference the schedule for it to be useful.

[mwetter]

Currently, writing to a schedule that is not in idf leads to an error. This is good, as otherwise if a user makes a typo in the schedule name, the simulation would run but results would not be affected.

In view of this, it may be best to require that an actuator is also in idf. Currently the set up is in idf:

EnergyManagementSystem:Actuator,
  Zn001_Wall001_Win001_Shading_Deploy_Status,  !- Name
  Zn001:Wall001:Win001,    !- Actuated Component Unique Name
  Window Shading Control,  !- Actuated Component Type
  Control Status;          !- Actuated Component Control Type

and in Modelica:

  Buildings.ThermalZones.EnergyPlus.Actuator actSha(
    name =          "Zn001_Wall001_Win001_Shading_Deploy_Status",
    unit =          Buildings.ThermalZones.EnergyPlus.Types.Units.Normalized,
    componentName = "Zn001:Wall001:Win001",
    componentType = "Window Shading Control",
    controlType =   "Control Status") "Actuator for window shade";

I suggest Modelica does not specify componentName, componentType and controlType as they are already in idf, or do you see any benefit of specifying them twice? And if they are specified twice, do they need to be consistent or is the idf entry ignored?

[mwetter]

@kbenne : Please provide a writeup for what this object does, how it behaves and how we best call it.

[mwetter]

@kbenne : Can you please review and propose changes if needed to the info section of
https://github.com/lbl-srg/modelica-buildings/blob/issue1633_schedulesActuators/Buildings/ThermalZones/EnergyPlus/Actuator.mo#L63

to make sure it is OK for user-facing documentation.