accim package

Subpackages

Submodules

accim.lists module

Lists to be used in the whole project.

accim.utils module

class accim.utils.AccimSimulationVerifier(eso_file_path: str, idf_path: str, eplus_install_dir: str | None = None)[source]

Bases: object

Object-oriented utility to verify ACCIM EMS simulation results.

This class reads an EnergyPlus simulation output (either .csv or .eso) and evaluates two primary checks to ensure adaptive comfort setups function correctly:

  • Check 1: Operative Temperature adherence within adjusted setpoint bounds (all timesteps).

  • Check 2: Window operation conditional logic for Mixed-Mode models (HVACmode = 2).

Parameters:

  • eso_file_path (str) – Absolute or relative path to the EnergyPlus output data. If an eplusout.csv file exists alongside the .eso, it is read directly to avoid the overhead of running ReadVarsESO. Otherwise the ESO is parsed via besos.

  • idf_path (str) – Path to the corresponding IDF model. Used to auto-discover EMS sensor names, window names, zone names, and control parameters (HVACmode, MaxWindSpeed, ACSTtol, AHSTtol) from the SetInputData EMS program.

  • eplus_install_dir (Optional[str], default None) – EnergyPlus installation directory, required by ReadVarsESO when falling back to .eso parsing.

summary

Human-readable string summarising violation counts for Check 1 and Check 2.

Type:

str

violations

Raw violation rows, one per flagged timestep. Keys are 'setpoint' and 'window'. Each DataFrame has columns: ['timestep', 'zone_or_window', 'check', 'description', 'value_found', 'value_expected'].

Type:

Dict[str, pd.DataFrame]

summary_table_setpoint

Aggregated count table for Check 1 violations, grouped by zone and check type. Columns: ['zone_or_window', 'check', 'count']. Empty if no violations.

Type:

pd.DataFrame

summary_table_window

Aggregated count table for Check 2 violations, grouped by window and condition. Columns: ['zone_or_window', 'check', 'count']. Empty if no violations.

Type:

pd.DataFrame

Check Identifiers
-----------------
The ``check`` column in the violation DataFrames uses the following identifiers
\*\*Check 1 -- Setpoint Adherence**
``Check1_TooHot``

The zone Operative Temperature (OpT) exceeds the adjusted cooling setpoint, defined as ACST_Sch - ACSTtol. ACST_Sch is the per-timestep adaptive cooling setpoint schedule computed by the EMS; ACSTtol is the tolerance margin subtracted to give the effective upper comfort band limit. EnergyPlus columns: Zone Operative Temperature, Schedule Value for ACST_Sch_<zone>. A single isolated spike (one timestep violated with no violation immediately before or after) is pardoned to absorb transient thermal shocks (e.g. a brief window opening that lets in cold/hot air).

``Check1_TooCold``

The zone Operative Temperature (OpT) falls below the adjusted heating setpoint, defined as AHST_Sch - AHSTtol. AHST_Sch is the per-timestep adaptive heating setpoint schedule; AHSTtol is the tolerance margin subtracted to give the effective lower comfort band limit. EnergyPlus columns: Zone Operative Temperature, Schedule Value for AHST_Sch_<zone>. Same single-spike pardon applies as for Check1_TooHot.

\*\*Check 2 -- Window Operation Logic (Mixed-Mode, HVACmode = 2)**
In Mixed-Mode the EMS program ``SetWindowOperation_<window>`` controls the ventilation
opening fraction every timestep. All seven conditions below must hold simultaneously
for the window to be legitimately open. A violation is flagged whenever the window is
open but any condition is not satisfied.
Automatic pardons are applied to account for the inherent one-timestep EMS actuation lag
- ``close_transit``

because the EMS detects the condition violation at timestep t but the close command only takes effect at timestep t+1.

Type:

the last open timestep before a window closing event is pardoned,

- ``just_turned_on``

reason: the window was still open when the HVAC came on, and the EMS closes it at t+1.

Type:

the first timestep of HVAC activation is pardoned for the same

- ``open_transit`` *(Hourly frequency only)*

is also pardoned, because hourly averaging of mixed on/off states within the hour produces artificial condition overlaps that do not represent true violations.

Type:

the first hour of a window opening block

``Check2_Cond1_HVACidle``

The mechanical system must not be active while the window is open. Mixed-Mode logic prohibits simultaneous HVAC and natural ventilation to prevent energy waste (e.g. conditioned air escaping through open windows). EnergyPlus columns: Cooling Coil Total Cooling Rate, Heating Coil Heating Rate. Condition: CoolingRate == 0 AND HeatingRate == 0.

``Check2_Cond2_Occupied``

The zone must be occupied for natural ventilation to activate. The EMS suppresses window opening when the zone is unoccupied to avoid unnecessary air infiltration. EnergyPlus column: People Occupant Count. Condition: OccupantCount > 0.

``Check2_Cond3_OpT_lt_ACST``

The zone Operative Temperature must be below the adaptive cooling setpoint. This ensures natural ventilation is only triggered when there is a genuine cooling need, i.e. indoor temperature has not yet reached the comfort upper limit. EnergyPlus columns: Zone Operative Temperature, Schedule Value for ACST_Sch_<zone> (minus ACSTtol). Condition: OpT < ACST_Sch - ACSTtol.

``Check2_Cond4_OpT_gt_VST``

The zone Operative Temperature must be above the Ventilation Setpoint Temperature (VST). VST is the lower thermal comfort bound: below it, natural ventilation would cause overcooling discomfort, so the window must stay closed. EnergyPlus column: EMS output Ventilation Setpoint Temperature – a per-timestep series computed dynamically by the EMS, not a static value. Condition: OpT > VST.

``Check2_Cond5_OutT_lt_OpT``

The outdoor air temperature must be lower than the indoor Operative Temperature for natural ventilation to be thermally effective. If outdoor air is warmer than indoors, opening windows would heat the space rather than cool it. EnergyPlus columns: Site Outdoor Air Drybulb Temperature, Zone Operative Temperature. Condition: OutdoorT < OpT.

``Check2_Cond6_MinOutTemp``

The outdoor air temperature must exceed the Minimum Outdoor Temperature threshold. This prevents natural ventilation when outdoor conditions are too cold, which could cause thermal discomfort or damage HVAC equipment. EnergyPlus column: EMS output Minimum Outdoor Temperature for ventilation – a per-timestep series computed dynamically by the EMS, not a static value. Condition: OutdoorT > MinOutTemp.

``Check2_Cond7_MaxWindSpeed``

The outdoor wind speed must not exceed the maximum allowed threshold. High wind speeds can cause excessive infiltration rates, draughts, or structural concerns. EnergyPlus column: Site Wind Speed. Condition: WindSpeed <= MaxWindSpeed, where MaxWindSpeed is a static scalar extracted from the SetInputData EMS program in the IDF.

Notes

Hourly frequency warning: Hourly outputs are averaged over the full hour, so a window that opens for only 10 minutes shows a fractional opening factor. Conditions that were mutually exclusive within the hour (e.g. HVAC active for 10 min, window open for 50 min) can appear to overlap in the hourly average, causing false positives. Sub-hourly (Timestep) output frequency is strongly recommended for accurate verification.

Required EnergyPlus outputs: All relevant Output:Variable objects must be present in the IDF. If any required column is missing from the CSV/ESO, a ValueError is raised identifying exactly which output is absent.

accim.utils.amend_idf_version_from_dsb(file_path: str)[source]

Amends the idf version of the Designbuilder-sourced idf file, for Designbuilder v7.X. Replaces the string ‘Version, 9.4.0.002’ with ‘Version, 9.4’.

Parameters:

idf_path (str) – the path to the idf

accim.utils.convert_standard_to_comfort_thermostats(idf: IDF, pmv_heating_schedule_name: str, pmv_cooling_schedule_name: str, comfort_control_type_schedule_name: str) → List[str][source]

Maps and substitutes standard DualSetpoint thermostats with Thermal Comfort Fanger thermostats.

Parameters:

  • idf (besos.IDF_class.IDF) – The BESOS IDF model object.

  • pmv_heating_schedule_name (str) – Name of the Schedule defining the PMV lower limit for heating.

  • pmv_cooling_schedule_name (str) – Name of the Schedule defining the PMV upper limit for cooling.

  • comfort_control_type_schedule_name (str) – Name of the Schedule that defines the control type.

Returns:

A list of Zone names that were successfully converted.

Return type:

List[str]

accim.utils.get_accim_args(idf_object: <module 'besos.IDF_class' from '/home/docs/checkouts/readthedocs.org/user_builds/accim/envs/master/lib/python3.9/site-packages/besos/IDF_class.py'>) → dict[source]

Collects all the EnergyManagementSystem:Program Program lines used to set the values for the arguments of ACCIS, and saves them in a dictionary.

Parameters:

idf_object – the besos.IDF_class instance

Returns:

a dictionary

accim.utils.get_accim_args_flattened(idf_object)[source]
accim.utils.get_available_fields(idf_instance: IDF, object_name: str, source: Literal['idd', 'idf'] = 'idd', separator: str = '_') → List[str][source]

Retrieves the available fields for an EnergyPlus object using an eppy IDF instance. It automatically removes colons (‘:’) from field names.

Parameters:

  • idf_instance (IDF) – The eppy IDF class instance (e.g., from besos.get_building()).

  • object_name (str) – The type of the object (e.g., ‘Zone’, ‘Material’).

  • source (str, optional) – The source of the field definitions. - ‘idd’: (Default) Extracts the full schema from the EnergyPlus dictionary. - ‘idf’: Extracts fields from the first existing instance in the model.

  • separator (str, optional) – Character to replace spaces with. Default is ‘_’. If “ “ is passed, the original spaces are kept.

Returns:

A list of formatted field names. Returns an empty list if an error occurs.

Return type:

List[str]

Raises:

ValueError – If ‘source’ is not ‘idd’ or ‘idf’.

accim.utils.get_idd_path_from_ep_version(EnergyPlus_version: str)[source]
accim.utils.get_idf_hierarchy(idf: <module 'besos.IDF_class' from '/home/docs/checkouts/readthedocs.org/user_builds/accim/envs/master/lib/python3.9/site-packages/besos/IDF_class.py'>) → Dict[str, Any][source]

Parses an EnergyPlus IDF model object (from eppy or besos) to extract the hierarchical relationship between Zones and Spaces, as well as grouping lists.

This function is designed to be Case-Preserving for output keys (keeping the original IDF capitalization) while remaining Case-Insensitive for internal logic (robustly linking Spaces to Zones regardless of capitalization).

Parameters:

idf (Union[IDF, IDF_class]) – The IDF model object to be parsed. Accepts both eppy’s IDF and besos’s IDF_class.

Returns:

A dictionary representing the model structure:
{
“zones”: {
“ZoneName_Original”: {

“object_type”: “Zone”, “spaces”: [“Space1”, “Space2”]

}, “groups”: {

”zone_lists”: { “ListName”: [“Zone1”, “Zone2”] }, “space_lists”: { “ListName”: [“Space1”, “Space2”] }

}

}

Return type:

Dict[str, Any]

accim.utils.get_idf_hierarchy_with_people(idf: IDF) → Dict[str, Any][source]

Parses an EnergyPlus IDF model to extract the hierarchy of Zones and Spaces.

Structure changes in this version: - ‘spaces’ is a list of dictionaries. - Each space dictionary contains:

  • “name”: The name of the space (str).

  • “people”: The name of the associated People object (str) or None.

The function resolves the ‘People’ object assignment regardless of whether it is assigned to a Space, a Zone, a SpaceList, or a ZoneList.

Parameters:

idf (besos.IDF_class.IDF) – The BESOS IDF model object.

Returns:

Structure:
{
“zones”: {
“ZoneName”: {

“object_type”: “Zone”, “spaces”: [

{

“name”: “SpaceName”, “people”: “PeopleObjectName” (or None)

]

}

}, “groups”: { … }

}

Return type:

Dict[str, Any]

accim.utils.get_people_hierarchy(idf: IDF) → Dict[str, Any][source]

Extracts the relationship between People objects and the physical Spaces they occupy.

Since a ‘People’ object can reference a Zone, a ZoneList, a Space, or a SpaceList, this function resolves all these references down to a list of specific Space names.

Parameters:

idf (Union[IDF, IDF_class]) – The IDF model object.

Returns:

A dictionary where keys are People object names and values

contain the target reference and the resolved list of spaces. Example: {

”Residential Living Occupants”: {

“target_ref”: “Residential - Living Space”, “target_type”: “SpaceList”, (inferred) “affected_spaces”: [“Floor_1”, “Floor_2”]

}

}

Return type:

Dict[str, Any]

accim.utils.get_people_names_for_ems(idf: IDF, output_format: str = 'list') → List[str] | Dict[str, List[str]][source]

Generates unique instance names for People objects applied to spaces.

Naming Pattern: “{SpaceName} {PeopleName}” Example: “Floor_1 Residential Living Occupants”

Parameters:

  • idf (besos.IDF_class.IDF) – The BESOS IDF model object.

  • output_format (str) – Controls the structure of the return value. - ‘list’ (Default): Returns a flat list of all generated names. - ‘dict’: Returns a dictionary {PeopleName: [GeneratedNames]}.

Returns:

A flat list or a dictionary depending on output_format.

Return type:

Union[List[str], Dict[str, List[str]]]

accim.utils.get_spaces_from_spacelist(idf: IDF, spacelist_name: str) → List[str][source]

Retrieves the list of Space names belonging to a specific SpaceList object.

Performs a case-insensitive search for the SpaceList name to ensure robustness.

Parameters:

  • idf (Union[IDF, IDF_class]) – The IDF model object.

  • spacelist_name (str) – The name of the SpaceList to query (e.g. “Residential - Living Space”).

Returns:

A list of space names contained in that SpaceList.

Returns an empty list [] if the SpaceList is not found.

Return type:

List[str]

accim.utils.identify_variable_key_pattern(idf_path: str, variable_name: str, epw_path: str, eplus_install_dir: str | None = None) → str[source]

Identifies the naming pattern (Key Index) used by EnergyPlus for a specific Report Variable.

This function performs a quick simulation to generate the .eso output file, extracts the actual ‘Key Value’ (Area) generated by EnergyPlus, and compares it against the IDF objects to determine the naming convention.

It uses a two-level search strategy: 1. Direct Object Match: Checks the first field of every object in the IDF (obj.obj[1])

to see if it matches the ESO Key. This handles systems like VRF, Boilers, Chillers, etc.

  1. Hierarchy Match: If no direct object is found, it analyzes the Zone/Space/People hierarchy to detect composite patterns (e.g., ‘[Space Name] [People Name]’).

Parameters:

  • idf_path – Path to the input .idf file.

  • variable_name – The name of the Output:Variable to analyze (e.g., ‘VRF Heat Pump Cooling Electricity Energy’).

  • epw_path – Path to the weather file (.epw) required for simulation.

  • eplus_install_dir – (Optional) Path to the EnergyPlus installation directory.

Returns:

A string representing the pattern with placeholders (e.g., ‘[AirConditioner:VariableRefrigerantFlow Name]’).

accim.utils.inspect_thermostat_objects(idf: IDF) → Dict[str, List[Dict[str, Any]]][source]

Inspects and retrieves key data from thermostat and setpoint objects in the IDF.

Target Objects:

  1. ZoneControl:Thermostat

  2. ZoneControl:Thermostat:ThermalComfort

  3. ThermostatSetpoint:DualSetpoint

  4. ThermostatSetpoint:ThermalComfort:Fanger:DualSetpoint

Parameters:

idf (besos.IDF_class.IDF) – The BESOS IDF model object.

Returns:

A dictionary where keys are the IDF Object Types

and values are lists of dictionaries containing the properties of each instance found.

Return type:

Dict[str, List[Dict[str, Any]]]

accim.utils.modify_timesteps(idf_object: IDF, timesteps: int) → IDF[source]

Modifies the timesteps of the idf object.

Parameters:

  • idf_object (IDF) – the IDF class from besos or eppy

  • timesteps (int) – The number of timesteps. Allowable values include 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, and 60

accim.utils.modify_timesteps_path(idfpath: str, timesteps: int)[source]

Modifies the timesteps of the idf.

Parameters:

  • idfpath (str) – the path to the idf

  • timesteps (int) – The number of timesteps. Allowable values include 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, and 60

class accim.utils.print_available_outputs_mod(building, version=None, name=None, frequency=None)[source]

Bases: object

accim.utils.read_eso_using_readvarseso(eso_file_path: str = 'eplusout.eso', eplus_install_dir: str | None = None, only_run_period: bool = True, cleanup: bool = True) → Dict[str, Dict[str, DataFrame]][source]

Lee el archivo .eso usando ReadVarsESO y parsea correctamente los nombres de objetos que contienen dos puntos (ej: Nombres de Zonas o Equipos VRF).

accim.utils.reduce_runtime(idf_object: IDF, minimal_shadowing: bool = True, shading_calculation_update_frequency: int = 20, maximum_figures_in_shadow_overlap_calculations: int = 200, timesteps: int = 6, runperiod_begin_month: int = 1, runperiod_begin_day_of_month: int = 1, runperiod_end_month: int = 1, runperiod_end_day_of_month: int = 1) → IDF[source]

Modifies the idf to reduce the simulation runtime.

Parameters:

  • idf_object

  • minimal_shadowing – True or False. If True, applies minimal shadowing setting.

  • shading_calculation_update_frequency – An integer. Sets the intervals for the shading calculation update

  • maximum_figures_in_shadow_overlap_calculations – An integer. Applies the number to the maximum figures in shadow overlap calculations.

  • timesteps – An integer. Sets the number of timesteps.

  • runperiod_begin_day_of_month – the day of the month to start the simulation

  • runperiod_begin_month – the month to start the simulation

  • runperiod_end_day_of_month – the day of the month to end the simulation

  • runperiod_end_month – the month to end the simulation

accim.utils.remove_accents(input_str: str) → str[source]
accim.utils.remove_accents_in_idf(idf_path: str)[source]

Replaces all letters with accent with the same letter without accent.

accim.utils.set_occupancy_to_always(idf_object: IDF) → IDF[source]

Sets the occupancy to always occupied for all zones with people object.

Parameters:

idf_object (IDF) – the IDF class from besos or eppy

accim.utils.set_occupancy_to_always_path(idfpath: str)[source]

Sets the occupancy to always occupied for all zones with people object.

Parameters:

idfpath (str) – the path to the idf

accim.utils.set_operative_temp_control(idf_path: str | None = None, idf_object=None)[source]

Sets the thermostat control to operative temperature for all ZoneControl:Thermostat objects. You can provide either the path to the IDF file or the eppy/besos IDF object.

Parameters:

  • idf_path – Path to the IDF file.

  • idf_object – eppy or besos IDF object.

Returns:

The modified IDF object if idf_object was provided, otherwise None.

accim.utils.transform_ddmm_to_int(string_date: str) → int[source]

This function converts a date string in the format “dd/mm” to the day of the year as an integer.

Parameters:

string_date – A string representing the date in format “dd/mm”

Returns:

The day of the year as an integer

Return type:

int

accim.utils.update_idf_version(input_idf_path: str, ep_version_target: str, output_idf_name: str | None = None, intermediate_idf_pattern: str | None = None) → None[source]

Updates an EnergyPlus IDF file to a target version by sequentially running the native EnergyPlus Transition tools.

This function operates inside an isolated temporary directory. This guarantees that all required EnergyPlus .idd files are present during execution, prevents legacy Fortran path/space bugs, and ensures your project directory isn’t littered with junk files (.idfold, .VCpErr, etc.).

Parameters:

  • input_idf_path (str) – Absolute or relative path to the source .idf file.

  • ep_version_target (str) – The desired target EnergyPlus version (e.g., “25.1” or “25.1.0”).

  • output_idf_name (str, optional) – The filename for the final updated IDF. Can optionally include the ‘{version}’ placeholder (e.g., “model_v{version}.idf”). If not provided, the script will overwrite the original input file.

  • intermediate_idf_pattern (str, optional) – The naming pattern for saving intermediate versions. MUST include the ‘{version}’ placeholder (e.g., “backup_step_{version}.idf”). If None, no intermediate files are saved.

Raises:

  • ValueError – If intermediate_idf_pattern lacks the ‘{version}’ placeholder, or if the initial IDF version cannot be read.

  • FileNotFoundError – If the target EnergyPlus transition directory cannot be found.

  • RuntimeError – If there is a missing transition tool to complete the chain.

  • subprocess.CalledProcessError – If the native EnergyPlus executable fails.

accim.utils.verify_accim_simulation(eso_file_path: str, idf_path: str, eplus_install_dir: str | None = None, tolerance: float = 0.1) → DataFrame[source]

Reads EnergyPlus simulation output and verifies that the ACCIS EMS scripts added by AddAccis are working correctly.

The function performs two categories of checks:

Check 1 – HVAC Setpoint Adherence (per zone): - If cooling is active (CoolCoil > 0): Zone Operative Temperature <= ACST_Sch + tolerance - If heating is active (HeatCoil > 0): Zone Operative Temperature >= AHST_Sch - tolerance

Check 2 – Window Operation Logic (per window in mixed-mode models): Replicates the explicit conditions of the EMS program SetWindowOperation_<windowname>:

HVACmode = 0 (HVAC only):

Window must be closed (VentOpenFact == 0).

HVACmode = 1 (Natural Ventilation priority — HVAC as backup):

Window may open only when ALL of the following: - HVAC coils are inactive (NoH_NoC_reqs == 1) - OpT < ACST (cooling need) - WindSpeed <= MaxWindSpeed - OutT > MinOutTemp - OutT < OpT - Occupancy > 0

And the VentCtrl sub-condition (for Ventilates_HVACmode1):

  • VentCtrl = 0: OutT < OpT, OutT > MinOutTemp, OpT > VST, WindSpeed <= MaxWindSpeed

  • VentCtrl = 1: OutT < OpT, OutT > MinOutTemp, OpT > ACSTnoTol, WindSpeed <= MaxWindSpeed

HVACmode = 2 (Changeover / Free-running):

Window may open when: NoH_NoC_reqs == 1 AND meets_base_reqs == 1 AND OpT > VST

Parameters:

  • eso_file_path (str) – Path to the eplusout.eso file.

  • idf_path (str) – Path to the IDF file used for simulation (to read accim args and window names).

  • eplus_install_dir (str, optional) – Path to EnergyPlus installation directory (for ReadVarsESO).

  • tolerance (float) – Temperature tolerance in °C for setpoint checks. Default is 0.1 °C.

Returns:

DataFrame with all detected mismatch timesteps, with columns [‘timestep’, ‘zone_or_window’, ‘check’, ‘description’, ‘value_found’, ‘value_expected’]. Empty DataFrame means all checks passed.

Return type:

pd.DataFrame

Module contents