Updated documentation and externalConfig

README.md

@@ -31,7 +31,7 @@ Standard usage of the AFC package follows the sequence of steps outlined in the
 The AFC package requires sets of parameters and inputs that describe the optimization problem. On the one hand, the parameters are quantities that describe the physical system on which the optimization is performed. Parameters include, for example, the location and size of the building, its number of windows or the number of occupants in the room. On the other hand, data inputs describe the climatic context of the optimization. These are essentially exogeneous meteorological forecasts of the sun's irradiance on the building. Unlike parameters, data inputs are time-dependent variables. 
 
 #### 1.1 Define system parameters
-The `parameter` object is a dictionary containing parameter values describing the system to be controlled by AFC. The built-in function `defaultConfing` contains default parameters which can be helpful to get started. Users can modify the parameters to create a setup that meets their specific building.
+The `parameter` object is a dictionary containing parameter values describing the system to be controlled by AFC. The built-in function `defaultConfing` contains default parameters which can be helpful to get started. Users can modify the parameters to create a setup that meets their specific building. An alternative way to establish the parameters is through a JSON test file. For more information see [here](docs/json_configuration.md).
 
 ```python
 # initialize afc with default parameters 
@@ -122,41 +122,48 @@ The AFC controller provides a variety of outputs ranging from the desired contro
 # get all outputs
 ctrl.get_output()
 # get only facade setpoints
-ctrl.get_output(keys=['uShade'])
+ctrl.get_output(keys=['output-data'])
 ```
 
 These full list of outputs is here:
-- `df_output`: Dataframe containing detailed time series data from the optimization (detailed below). Typically only used for debugging or visualizations.
-- `duration`: Total duration of the whole controller iteration, in sec.
-- `glaremode`: Indication if any of the window zones is in glare mode, as a list of booleans.
-- `glare_duration`: Duration to calculate window glare modes, in sec.
-- `optall_duration`: Total duration of the optimization process, in sec.
-- `opt_duration`: Duration to solve the optimization problem, in sec.
-- `opt_objective`: Optimal value of the objective function.
-- `opt_termination`: Status of optimization indicating whether the solver has reached an optimal solution, as string.
-- `outputs_duration`: Duration to generate the outputs, in sec.
-- `rad_duration`: Duration to calculate the radiance inputs, in sec.
-- `uShade`: Control setpoint for dynamic facade, as list of setpoints for each zone.
-- `uTroom`: Control setpoint for HVAC thermostat, in °C.
-- `varts_duration`: Duration to resample for variable-timestep inputs, in sec.
-
-The `df_output` is a special entry as it contains time series data for all the inputs and outputs of the optimization process. It is not necessary for a general user to understand these, but might be important for developers or debugging. The `df_output` can be formatted into a pandas dataframe and subsequently easily plotted and analyzed:
+- `output-data`: Dataframe containing detailed time series data from the optimization (detailed below). Typically only used for debugging or visualizations.
+- `ctrl-facade`: Control setpoint for dynamic facade, as list of setpoints for each zone.
+- `ctrl-thermostat`: 
+    - `feasible`: Boolean set to ‘True’ if the controller has been able to find optimal setpoints. 
+    - `mode`: Operational mode of the HVAC system. Possible values are ‘X’ for no control, ‘F’ for floating, ‘C’ for cooling, and ‘H’ for heating
+    - `csp`: Control setpoint for cooling thermostat, in °C.
+    - `hsp`: Control setpoint for heating thermostat, in °C.
+- `ctrl-troom`: Control setpoint for HVAC thermostat, in °C.
+- `duration`: 
+    - `all`: Total duration of the whole controller iteration, in sec.
+    - `glare`: Duration to calculate window glare modes, in sec.
+    - `optall`: Total duration of the optimization process, in sec.
+    - `outputs`: Duration to solve the optimization problem, in sec.
+    - `radiance`: Duration to calculate the radiance inputs, in sec.
+    - `varts`: duration to resample for variable-timestep inputs, in sec.
+- `opt-stats`:
+    - `duration`: Duration of the optimization, in sec.
+    - `objective`: Optimal value of the objective function.
+    - `termination`: Status of optimization indicating whether the solver has reached an optimal solution, as string.
+
+
+The `output-data` is a special entry as it contains time series data for all the inputs and outputs of the optimization process. It is not necessary for a general user to understand these, but might be important for developers or debugging. The `output-data` can be formatted into a pandas dataframe and subsequently easily plotted and analyzed:
 
 ```python
 # convert df_outputs to pandas
-df = pd.DataFrame(ctrl.get_output(keys=['df_output'])['df_output'])
+df = pd.DataFrame(ctrl.get_output(keys=['output-data'])['output-data'])
 df.index = pd.to_datetime(df.index, unit='ms')
-# remove slab constraints for plotting
-df['Temperature 1 Min [C]'] = None
-df['Temperature 1 Max [C]'] = None
+
 # make exmaple plot of results
 from afc.utility.plotting import plot_standard1
-plot_standard1(pd.concat([wf, df], axis=1).ffill().iloc[:-1])
+plot_standard1(df.iloc[:-1])
+
 ```
 
-The detailed time series output data stored in `df_output` is provided as indexed dictionary:
+The detailed time series output data stored in `output-data` is provided as indexed dictionary:
 - `artificial Illuminance`: Illuminance provided by artificial lighting, in lux.
 - `export Power`: Electricity generated local generation which is fed back into the grid, in kW.
+- `GHG Emissions`: Emissions associated with heating/cooling the room, in kg.
 - `hour`: Hour of the day.
 - `import Power`: Total amount of electricity consumed by the whole building site, in kW.
 - `load Power`: Amount of electricity consumed by the building, in kW.

afc/externalConfig.py

@@ -27,7 +27,8 @@ def read_json_config(config_path, json_only=False):
 
     Args: 
         config_path (str): path to the json configuration file
-        json_only (bool): boolean determining whether to return only the json configuration data or use it to update the AFC parameters.
+        json_only (bool): boolean determining whether to return only
+        the json configuration data or use it to update the AFC parameters.
         
     Returns:
         if json_only == TRUE:

docs/json_configuration.md

@@ -0,0 +1,42 @@
+## Defining JSON user inputs
+
+The simplest way for a user to set up the AFC controller is through a dedicated JSON configuration file, an example can be found [here](https://github.com/LBNL-ETA/AFC/blob/master/afc/resources/config/example_config.json). Here the user is able to adjust model parameters and preferences without any interaction with the Python code. Below is a list of these inputs and their meanings:
+
+```python
+from afc.externalConfig import read_json_config, DEFAULT_JSON_PATH
+
+# Path to json configuration
+json_config_path = DEFAULT_JSON_PATH
+
+# Create the inputs vector
+parameter = read_json_config(json_config_path)
+inputs = make_inputs(parameter, wf)
+```
+
+- `building_age`: [str] Indicator of building vintage. Used to update `parameter[‘zone’][‘param’]`. Default value is 'new-constr'. Possible values are 'new-constr', 'post-1980' and 'pre-1980'.
+- `debug`: [bool] Flag to enable console printing of the solver. Used to update `parameter[‘wrapper’][‘printing’]`. Default value is ‘False’.
+- `interface_status`: [str] Status from the user interface. Default value is 'Updated Configuration'.
+- `location_city`: [str] City location of the building. Default value is ‘Berkeley’.
+- `location_latitude`: [float] Latitude of the building, in degree. Used to update `parameter[‘radiance’][‘location’][‘latitude’]`. Default value is 37.85.
+- `location_longitude`: [float] Longitude of the building, in degree. Used to update `parameter[‘radiance’][‘location’][‘longitude’]`. Default value is -122.24.
+- `location_orientation`: [float] Orientation of the building, in angular degree. Note that 0 corresponds to South. Used to update `parameter[‘radiance’][‘location’][‘orientation’]`. Default value is 180.
+- `location_state`: [str] State location of the building. Default value is ‘CA’.
+- `occupant_1_direction` [int] Orientation of the occupant inside the building, in degree relative to the building orientation. For ‘orientation’ 0 deg (South) a ‘view_orient’ of -90 would correspond towards East. Used to update `parameter[‘radiance’][‘location’][‘view_orient’]`. Default value is 0.
+- `occupant_brightness` [int] Occupant preference for minimum work plane illuminance. Used to map `parameter[‘occupant’][‘wpi_min’]`. Default value is 100% (350lx).
+- `occupant_glare` [float] Occupant preference for maximum acceptable glare. Used to map `parameter[‘occupant’][‘glare_max’]`. Default value is 100% (0.4). 
+- `occupant_number` [int] Number of occupants in the room. Used as multiple to update unitary metrics such as the electric equipment load (`parameter[‘occupant’][‘equipment’]`), thermal plug load (`parameter[‘occupant’][‘plug_load’]`) and thermal occupant load (`parameter[‘occupant’][‘occupant_load’]`). Default value is 1.
+- `room_depth` [int] Depth of the building, in feet. Used to update `parameter[‘radiance’][‘dimensions’][‘depth’]`. Default value is 15.
+- `room_height` [int] Height of the building, in feet. Used to update `parameter[‘radiance’][‘dimensions’][‘height’]`. Default value is 11.
+- `room_width` [int] Width of the building, in feet. Used to update `parameter[‘radiance’][‘dimensions’][‘width’]`. Default value is 10.
+- `system_cooling` [str] Type of energy used by the cooling system. Default value is ‘el’ (for electric). No other technologies are implemented at this time.
+- `system_cooling_eff` [float] The coefficient of performance of the cooling system. Used to update `parameter[‘zone’][‘cooling_efficiency’]`. Default value is 3.5.
+- `system_heating` [str] Type of energy used by the heating system. Default value is ‘el’ (for electric). No other technologies are implemented at this time.
+- `system_heating_eff` [float] Electric efficiency of the heating system. If the heating system type is electric, then it is used to update `parameter[‘zone’][‘heating_efficiency’]`. Otherwise, the latter parameter is set to 1. Default value is 0.95.
+- `system_id` [str] Unique instance identifier. Used to update `parameter[‘wrapper’][‘instance_id’]`. Default value is ‘Test-AAA’.
+- `system_light` [str] Type of the lighting system. Used to map `parameter[‘zone’][‘lighting_efficiency’]`. Possible values are fluorescent (‘FLU’) which sets efficiency to 0.5 W/lux and ‘LED’ which sets it to 0.25 W/lux. Default value is ‘FLU’.
+- `system_type` [str] Type of the facade. Used to update `parameter[‘facade’][‘type’]`. Currently only supports the default (three-zone electrochromic window). Default value is 'ec-71t'.
+- `tariff_name` [str] Name of the used tariff rate. Used to update `parameter[‘wrapper’][‘tariff_name’]`. A full list of available tariffs can be found in the DOPER documentation [here](https://github.com/LBNL-ETA/DOPER/blob/master/doper/data/tariff.py). Default value is 'e19-2020'.
+- `window_count` [int] Number of windows on the building facade. Used to multiply the window width. Used to update the coordinates in `parameter[‘radiance’][‘dimensions’][‘windows1’]`, `parameter[‘radiance’][‘dimensions’][‘windows2’]`, and `parameter[‘radiance’][‘dimensions’][‘windows3’]`. Default value is 2.
+- `window_height` [float] Height of a window, in feet. Used to update the coordinates in `parameter[‘radiance’][‘dimensions’][‘windows1’]`, `parameter[‘radiance’][‘dimensions’][‘windows2’]`, and `parameter[‘radiance’][‘dimensions’][‘windows3’]`. Default value is 8.5.
+- `window_sill` [float] Sill of a window, in feet. Used to update the coordinates in `parameter[‘radiance’][‘dimensions’][‘windows1’]`, `parameter[‘radiance’][‘dimensions’][‘windows2’]`, and `parameter[‘radiance’][‘dimensions’][‘windows3’]`. Default value is 0.5.
+- `window_width` [float] Width of a window, in feet. Used to update the coordinates in `parameter[‘radiance’][‘dimensions’][‘windows1’]`, `parameter[‘radiance’][‘dimensions’][‘windows2’]`, and `parameter[‘radiance’][‘dimensions’][‘windows3’]`. Default value is 4.5.