archetypal.idfclass.IDF

class archetypal.idfclass.IDF(idfname: Optional[Union[str, IO, path.Path]] = None, epw=None, as_version: Union[str, archetypal.eplus_interface.version.EnergyPlusVersion] = '9-2-0', annual=False, design_day=False, expandobjects=False, convert=False, verbose=False, readvars=True, prep_outputs=True, include=None, custom_processes=None, output_suffix='L', epmacro=False, keep_data=True, keep_data_err=True, position=0, name=None, output_directory=None, outputtype='standard', iddname: Optional[Union[str, IO, path.Path]] = None, **kwargs)

Class for loading and parsing idf models.

This is the starting point to run simulations and retrieving results.

Wrapper over the geomeppy.IDF class and subsequently the eppy.modeleditor.IDF class.

Initialize an IDF object.

Parameters

• output_directory –

• idfname (str or os.PathLike) – The path of the idf file to read. If none, an in-memory IDF object is generated.

• epw (str or os.PathLike) – The weather-file. If None, epw can be specified in IDF.simulate().

• as_version (str) – Specify the target EnergyPlus version for the IDF model. If as_version is higher than the file version, the model will be transitioned to the target version. This will not overwrite the file unless IDF.save() is invoked. See IDF.save(), IDF.saveas() and IDF.savecopy() for other IO operations on IDF objects.

• annual (bool) – If True then force annual simulation (default: False).

• design_day (bool) – Force design-day-only simulation (default: False).

• expandobjects (bool) – Run ExpandObjects prior to simulation (default: True).

• convert (bool) – If True, only convert IDF->epJSON or epJSON->IDF.

• outputtype (str) – Specifies the idf string representation of the model. Choices are: “standard”, “nocomment1”, “nocomment2”, “compressed”.

EnergyPlus args:

tmp_dir=None, as_version=None, prep_outputs=True, include=None, keep_original=True,

classmethod from_example_files(example_name, epw=None, **kwargs)

Load an IDF model from the ExampleFiles folder by name.

Examples

idf = IDF.from_example_files(

“minimal”, “USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw”

)

Parameters

• example_name (str) – The name of the example file to load.

• epw (str) – The name of the weather file contained the WeatherData folder or the path to a specific weather file.

• **kwargs – keyword arguments passed to the IDF constructor.

Returns

An IDF model.

Return type

(IDF)

setiddname(iddname, testing=False)

Set EnergyPlus IDD path for model.

Sets the version of EnergyPlus which is to be used by eppy.

Parameters

• iddname (str) – Path to the IDD file.

• testing (bool) –

read()

Read the IDF file and the IDD file.

If the IDD file had already been read, it will not be read again.

Read populates the following data structures:

• idfobjects : list

• model : list

• idd_info : list

• idd_index : dict

getiddname()

Get the name of the current IDD used by eppy.

setidd(iddinfo, iddindex, block, idd_version)

Set the IDD to be used by eppy.

Parameters

• iddindex –

• iddinfo (list) – Comments and metadata about fields in the IDD.

• block (list) – Field names in the IDD.

property block: list

Set EnergyPlus field ID names of the IDF from the IDD.

property idd_info: list

Set comments and metadata about fields in the IDD.

property idd_index: dict

Set pair of dicts used for fast lookups of names of groups of objects.

property idfobjects: dict

Set dict of lists of idf_MSequence objects in the IDF.

property model: eppy.EPlusInterfaceFunctions.eplusdata.Eplusdata

Set Eplusdata object containing representations of IDF objects.

property idd_version: tuple

Return the version of the iddname as a tuple.

property iddname: path.Path

Get or set the iddname path used to parse the idf model.

property file_version: archetypal.eplus_interface.version.EnergyPlusVersion

Return the EnergyPlusVersion of the idf text file.

property custom_processes: list

Return list of callables. Called on the output files.

property include: list

Return list of external files attached to model.

property keep_data_err: bool

If True, error files are copied back into self.output_folder.

Type

bool

property keep_data: bool

If True, keep data folder.

Type

bool

property output_suffix: str

L).

• L: Legacy (e.g., eplustbl.csv)

• C: Capital (e.g., eplusTable.csv)

• D: Dash (e.g., eplus-table.csv)

Type

str

Type

The suffix style for output file names (default

property idfname: Union[path.Path, _io.StringIO]

The path of the active (parsed) idf model.

Type

Path

property epw: path.Path

The weather file path.

Type

Path

property verbose

If True, print outputs to logging module.

See also

archetypal.utils.config

Type

bool

property expandobjects: bool

If True, run ExpandObjects prior to simulation.

Type

bool

property readvars: bool

If True, run ReadVarsESO after simulation.

Type

bool

property epmacro: bool

If True, run EPMacro prior to simulation.

Type

bool

property design_day: bool

If True, force design-day-only simulation.

Type

bool

property annual: bool

If True, force annual simulation.

Type

bool

property convert: bool

If True, only convert IDF->epJSON or epJSON->IDF.

Dependent on input file type. No simulation.

Type

bool

property prep_outputs

Bool or set list of custom outputs.

property as_version

Specify the desired EnergyPlusVersion for the IDF model.

property output_directory: path.Path

The output directory based on the hashing of the original file.

Notes

The hashing is performed before transitions or modifications. The directory is not created! Use self.output_directory.makedir_p() to create it without an error if it exists.

Type

Path

property output_prefix: str

eplus).

Type

str

Type

Prefix for output file names (default

property sim_id: str

The unique Id of the simulation.

Based on a subset of hashed variables:

• The idf model itself.

• epw

• annual

• design_day

• readvars

• as_version

Type

str

property sim_info: Optional[pandas.core.frame.DataFrame]

Unique number generated for a simulation.

Type

DataFrame

property sim_timestamp: Union[str, pandas.core.series.Series]

Return the simulation timestamp or “Never” if not ran yet.

property position: int

Position for the progress bar.

Type

int

property idfversionupdater_dir: path.Path

The path of the IDFVersionUpdater folder.

Uses the current module’s ep_version.

Type

Path

property name: str

Name of the idf model.

Can include the extension (.idf).

Type

str

sql() → dict

Get the sql table report.

htm() → dict

Get the htm table report.

property energyplus_its: int

Return number of iterations needed to complete simulation.

open_htm()

Open .htm file in browser.

open_idf()

Open file in correct version of Ep-Launch.

open_last_simulation()

Open last simulation in Ep-Launch.

open_err()

Open last simulation err file in texteditor.

open_mdd()

Open .mdd file in browser.

This file shows all the report meters along with their “availability” for the current input file.

open_mtd()

Open .mtd file in browser.

This file contains the “meter details” for the run. This shows what report variables are on which meters and vice versa – which meters contain what report variables.

property sql_file

Get the sql file path.

property mtd_file: path.Path

Get the mtd file path.

property net_conditioned_building_area: float

Return the total conditioned area of a building.

Takes into account zone multipliers.

property unconditioned_building_area: float

Return the Unconditioned Building Area.

property total_building_area: float

Return the Total Building Area.

property partition_ratio: float

Lineal meters of partitions per m2 of floor area.

Type

float

add_block(*args: Any, **kwargs: Any) → None

Add a block to the IDF.

Parameters

• name – A name for the block.

• coordinates – A list of (x, y) tuples representing the building outline.

• height – The height of the block roof above ground level.

• num_stories – The total number of stories including basement stories. Default : 1.

• below_ground_stories – The number of stories below ground. Default : 0.

• below_ground_storey_height – The height of each basement storey. Default : 2.5.

• zoning – The zoning pattern of the block. Default : by_storey

• perim_depth – Depth of the perimeter zones if the core/perim zoning pattern is requested. Default : 3.0.

add_shading_block(*args: Any, **kwargs: Any) → None

Add a shading block to the IDF.

Parameters

• name – A name for the block.

• coordinates – A list of (x, y) tuples representing the building outline.

• height – The height of the block roof above ground level.

• num_stories – The total number of stories including basement stories. Default : 1.

• below_ground_stories – The number of stories below ground. Default : 0.

• below_ground_storey_height – The height of each basement storey. Default : 2.5.

add_zone(zone: geomeppy.builder.Zone) → None

Add a zone to the IDF.

Parameters

zone – A Zone object holding details about the zone.

bounding_box() → geomeppy.geom.polygons.Polygon2D

Calculate the site bounding box.

Returns

A polygon of the bounding box.

property centroid

Calculate the centroid of the site bounding box.

Returns

The centroid of the site bounding box.

copyidfobject(idfobject: geomeppy.patches.EpBunch) → geomeppy.patches.EpBunch

Add an IDF object to the IDF.

This has been monkey-patched to add the return value.

Parameters

idfobject – The IDF object to copy. Usually from another IDF, or it can be used to copy within this IDF.

Returns

EpBunch object.

getextensibleindex(key, name)

Get the index of the first extensible item.

Only for internal use. # TODO : hide this

Parameters

• key (str) – The type of IDF object. This must be in ALL_CAPS.

• name (str) – The name of the object to fetch.

Returns

Return type

int

getiddgroupdict()

Return a idd group dictionary sample: {‘Plant-Condenser Loops’: [‘PlantLoop’, ‘CondenserLoop’], ‘Compliance Objects’: [‘Compliance:Building’], ‘Controllers’: [‘Controller:WaterCoil’, ‘Controller:OutdoorAir’, ‘Controller:MechanicalVentilation’, ‘AirLoopHVAC:ControllerList’], …}

Returns

Return type

dict

getobject(key, name)

Fetch an IDF object given key and name.

Parameters

• key (str) – The type of IDF object. This must be in ALL_CAPS.

• name (str) – The name of the object to fetch.

Returns

Return type

EpBunch object.

getshadingsurfaces(surface_type: str = '') → Union[List[eppy.bunch_subclass.EpBunch], eppy.idf_msequence.Idf_MSequence]

Return all subsurfaces in the IDF.

Parameters

surface_type – Type of surface to get. Defaults to all.

Returns

IDF surfaces.

getsubsurfaces(surface_type: str = '') → Union[List[eppy.bunch_subclass.EpBunch], eppy.idf_msequence.Idf_MSequence]

Return all subsurfaces in the IDF.

Parameters

surface_type – Type of surface to get. Defaults to all.

Returns

IDF surfaces.

getsurfaces(surface_type: str = '') → Union[List[eppy.bunch_subclass.EpBunch], eppy.idf_msequence.Idf_MSequence]

Return all surfaces in the IDF.

Parameters

surface_type – Type of surface to get. Defaults to all.

Returns

IDF surfaces.

idfstr()

String representation of the IDF.

Returns

Return type

str

initnew(fname)

Use the current IDD and create a new empty IDF. If the IDD has not yet been initialised then this is done first.

Parameters

fname (str, optional) – Path to an IDF. This does not need to be set at this point.

initread(idfname)

Use the current IDD and read an IDF from file. If the IDD has not yet been initialised then this is done first.

Parameters

idf_name (str) – Path to an IDF file.

initreadtxt(idftxt)

Use the current IDD and read an IDF from text data. If the IDD has not yet been initialised then this is done first.

Parameters

idftxt (str) – Text representing an IDF file.

intersect() → None

Intersect all surfaces in the IDF.

intersect_match() → None

Intersect all surfaces in the IDF, then set boundary conditions.

match() → None

Set boundary conditions for all surfaces in the IDF.

new(fname=None)

Create a blank new idf file. Filename is optional.

Parameters

fname (str, optional) – Path to an IDF. This does not need to be set at this point.

popidfobject(key, index)

Pop an IDF object from the IDF.

Parameters

• key (str) – The type of IDF object. This must be in ALL_CAPS.

• index (int) – The index of the object to pop.

Returns

Return type

EpBunch object.

printidf()

Print the IDF.

removeextensibles(key, name)

Remove extensible items in the object of key and name.

Only for internal use. # TODO : hide this

Parameters

• key (str) – The type of IDF object. This must be in ALL_CAPS.

• name (str) – The name of the object to fetch.

Returns

Return type

EpBunch object

rotate(angle: float, anchor: Optional[Union[geomeppy.geom.vectors.Vector2D, geomeppy.geom.vectors.Vector3D]] = None) → None

Rotate the IDF counterclockwise by the angle given.

Parameters

• angle – Angle (in degrees) to rotate by.

• anchor – Point around which to rotate. Default is the centre of the the IDF’s bounding box.

run(**kwargs)

This method wraps the following method:

rruunn(idf=None, weather=None, output_directory=’’, annual=False, design_day=False, idd=None, epmacro=False, expandobjects=False, readvars=False, output_prefix=None, output_suffix=None, version=False, verbose=’v’, ep_version=None)

Wrapper around the EnergyPlus command line interface.

idfstr

Full or relative path to the IDF file to be run, or an IDF object.

weatherstr

Full or relative path to the weather file.

output_directorystr, optional

Full or relative path to an output directory (default: ‘run_outputs)

annualbool, optional

If True then force annual simulation (default: False)

design_daybool, optional

Force design-day-only simulation (default: False)

iddstr, optional

Input data dictionary (default: Energy+.idd in EnergyPlus directory)

epmacrostr, optional

Run EPMacro prior to simulation (default: False).

expandobjectsbool, optional

Run ExpandObjects prior to simulation (default: False)

readvarsbool, optional

Run ReadVarsESO after simulation (default: False)

output_prefixstr, optional

Prefix for output file names (default: eplus)

output_suffixstr, optional

Suffix style for output file names (default: L)

L: Legacy (e.g., eplustbl.csv) C: Capital (e.g., eplusTable.csv) D: Dash (e.g., eplus-table.csv)

versionbool, optional

Display version information (default: False)

verbose: str

Set verbosity of runtime messages (default: v)

v: verbose q: quiet

ep_version: str

EnergyPlus version, used to find install directory. Required if run() is called with an IDF file path rather than an IDF object.

str : status

CalledProcessError

AttributeError

If no ep_version parameter is passed when calling with an IDF file path rather than an IDF object.

scale(factor: float, anchor: Optional[Union[geomeppy.geom.vectors.Vector2D, geomeppy.geom.vectors.Vector3D]] = None, axes: str = 'xy') → None

Scale the IDF by a scaling factor.

Parameters

• factor – Factor to scale by.

• anchor – Point to scale around. Default is the centre of the the IDF’s bounding box.

• axes – Axes to scale on. Default ‘xy’.

property simulation_files: list

The list of files generated by the simulation.

Type

list

to_obj(fname: Optional[str] = None, mtllib: Optional[str] = None) → None

Export an OBJ file representation of the IDF.

This can be used for viewing in tools which support the .obj format.

Parameters

• fname – A filename for the .obj file. If None we try to base it on IDF.idfname and change the filetype.

• mtllib – The name of a .mtl file to be referenced from the .obj file. If None, we use default.mtl.

translate(vector: geomeppy.geom.vectors.Vector2D) → None

Move the IDF in the direction given by a vector.

Parameters

vector – A vector to translate by.

translate_to_origin() → None

Move an IDF close to the origin so that it can be viewed in SketchUp.

view_model(test: Optional[bool] = False) → None

Show a zoomable, rotatable representation of the IDF.

property simulation_dir: path.Path

The path where simulation results are stored.

Type

Path

property schedules_dict: dict

schedule} in the model.

Type

Return the dict of {NAME

property outputs: archetypal.idfclass.outputs.Outputs

Return the Outputs class associated with the model.

property day_of_week_for_start_day

Get day of week for start day for the first found RUNPERIOD.

Monday = 0 .. Sunday = 6

property meters: archetypal.idfclass.meters.Meters

List of available meters for the IDF model.

The IDF model must be simulated once (to retrieve the .mdd file).

The listed meters may or may not be included in the idf file. If they are not, the output is added to the file and the model is simulated again. The output is appended to the IDF.idfobjects list, but will not overwrite the original idf file, unless IDF.save() is called.

Hint

Call idf.meters.<output_group>.<meter_name>.values() to retreive a time-series based on the pandas.Series class which can be plotted.

See Meter and EnergySeries for more information.

Example

The IDF.meters attribute is populated with meters categories (Output:Meter or Output:Meter:Cumulative) and each category is populated with all the available meters.

>>> IDF.meters.OutputMeter.WaterSystems__MainsWater
>>> IDF.meters.OutputMeterCumulative.WaterSystems__MainsWater

property variables

List of available meters for the IDF model.

The IDF model must be simulated once (to retrieve the .mdd file).

The listed meters may or may not be included in the idf file. If they are not, the output is added to the file and the model is simulated again. The output is appended to the IDF.idfobjects list, but will not overwrite the original idf file, unless IDF.save() is called.

Hint

Call idf.meters.<output_group>.<meter_name>.values() to retreive a time-series based on the pandas.Series class which can be plotted.

See Meter and EnergySeries for more information.

Example

The IDF.meters attribute is populated with meters categories (Output:Meter or Output:Meter:Cumulative) and each category is populated with all the available meters.

>>> IDF.variables.OutputVariable
>>> IDF.variables.OutputVariable

simulate(force=False, **kwargs)

Execute EnergyPlus.

Specified kwargs overwrite IDF parameters. ExpandObjects, Basement and Slab preprocessors are ran before EnergyPlus.

Does not return anything.

Parameters

force (bool) – Force simulation even though results exist in self.simulation_dir.

Keyword Arguments

• eplus_file (str) – path to the idf file.

• weather_file (str) – path to the EPW weather file.

• output_directory (str, optional) – path to the output folder.

• ep_version (str, optional) – EnergyPlus executable version to use, eg: 9-2-0

• output_report – ‘sql’ or ‘htm’

• prep_outputs (bool or list, optional) – if True, meters and variable outputs will be appended to the idf files. Can also specify custom outputs as list of ep-object outputs.

• keep_data (bool) – If True, files created by EnergyPlus are saved to the tmp_dir.

• annual (bool) – If True then force annual simulation (default: False)

• design_day (bool) – Force design-day-only simulation (default: False)

• epmacro (bool) – Run EPMacro prior to simulation (default: False)

• expandobjects (bool) – Run ExpandObjects prior to simulation (default: True)

• readvars (bool) – Run ReadVarsESO after simulation (default: False)

• output_prefix (str, optional) – Prefix for output file names.

• output_suffix (str, optional) –

  Suffix style for output file names (default: L) Choices are:

  • L: Legacy (e.g., eplustbl.csv)

  • C: Capital (e.g., eplusTable.csv)

  • D: Dash (e.g., eplus-table.csv)

• version (bool, optional) – Display version information (default: False)

• verbose (str) – Set verbosity of runtime messages (default: v) v: verbose q: quiet

• keep_data_err (bool) – If True, errored directory where simulation

• is (occurred) – kept.

• include (str, optional) – List input files that need to be copied to the simulation directory. If a string is provided, it should be in a glob form (see pathlib.Path.glob()).

• process_files (bool) – If True, process the output files and load to a DataFrame. Custom processes can be passed using the custom_processes attribute.

• custom_processes (dict(Callback)) – if provided, it has to be a dictionary with the keys being a glob (see pathlib.Path.glob()), and the value a Callback taking as signature callback(file: str, working_dir, simulname) -> Any All the file matching this glob will be processed by this callback. Note: they will still be processed by pandas.read_csv (if they are csv files), resulting in duplicate. The only way to bypass this behavior is to add the key “*.csv” to that dictionary.

• return_idf (bool) – If True, returns the IDF object part of the return tuple.

• return_files (bool) – It True, all files paths created by the EnergyPlus run are returned.

Raises

EnergyPlusProcessError – If an issue occurs with the execution of the energyplus command.

See also

IDF.simulation_files, IDF.processed_results for simulation outputs.

savecopy(filename, lineendings='default', encoding='latin-1')

Save a copy of the file with the filename passed.

Parameters

• filename (str) – Filepath to save the file.

• lineendings (str) – Line endings to use in the saved file. Options are ‘default’, ‘windows’ and ‘unix’ the default is ‘default’ which uses the line endings for the current system.

• encoding (str) – Encoding to use for the saved file. The default is ‘latin-1’ which is compatible with the EnergyPlus IDFEditor.

Returns

The new file path.

Return type

Path

copy()

Return a copy of self as an in memory IDF.

The copy is a new IDF object with the same parameters and arguments as self but is not attached to an file. Use IDF.saveas(“idfname.idf”, inplace=True) to save the copy to a file inplace. self.idfname will now be idfname.idf

save(lineendings='default', encoding='latin-1', **kwargs)

Write the IDF model to the text file.

Uses save() but also brings over existing simulation results.

Parameters

• lineendings (str) – Line endings to use in the saved file. Options are ‘default’, ‘windows’ and ‘unix’ the default is ‘default’ which uses the line endings for the current system.

• encoding (str) – Encoding to use for the saved file. The default is ‘latin-1’ which is compatible with the EnergyPlus IDFEditor.

Returns

The IDF model

Return type

IDF

saveas(filename, lineendings='default', encoding='latin-1', inplace=False)

Save the IDF model as.

Writes a new text file and load a new instance of the IDF class (new object).

Parameters

• filename (str) – Filepath to save the file. If None then use the IDF.idfname parameter. Also accepts a file handle.

• lineendings (str) – Line endings to use in the saved file. Options are ‘default’, ‘windows’ and ‘unix’ the default is ‘default’ which uses the line endings for the current system.

• encoding (str) – Encoding to use for the saved file. The default is ‘latin-1’ which is compatible with the EnergyPlus IDFEditor.

• inplace (bool) – If True, applies the new filename to self directly, else a new object is returned with the new filename.

Returns

A new IDF object based on the new location file.

Return type

IDF

process_results()

Return the list of processed results.

Processes are defined by custom_processes as a list of tuple(file, result). A default process looks for csv files and tries to parse them into DataFrame objects.

Returns

List of two-tuples.

Return type

list

Info:

For processed_results to work more consistently, it may be necessary to add the “readvars=True” parameter to IDF.simulate() as this one is set to false by default.

add_idf_object_from_idf_string(idf_string)

Add an IDF object (or more than one) from an EnergyPlus text string.

Parameters

idf_string (str) – A text string fully describing an EnergyPlus object.

upgrade(to_version=None, overwrite=True)

EnergyPlus idf version updater using local transition program.

Update the EnergyPlus simulation file (.idf) to the latest available EnergyPlus version installed on this machine. Optionally specify a version (eg.: “9-2-0”) to aim for a specific version. The output will be the path of the updated file. The run is multiprocessing_safe.

Hint

If attempting to upgrade an earlier version of EnergyPlus (pre-v7.2.0), specific binaries need to be downloaded and copied to the EnergyPlus*/PreProcess/IDFVersionUpdater folder. More info at Converting older version files.

Parameters

• to_version (str, optional) – EnergyPlus version in the form “X-X-X”.

• overwrite (bool) – If True, original idf file is overwritten with new transitioned file.

Raises

• EnergyPlusProcessError – If version updater fails.

• EnergyPlusVersionError –

• CalledProcessError –

wwr(azimuth_threshold=10, round_to=10)

Return the Window-to-Wall Ratio by major orientation.

Optionally round up the WWR value to nearest value (eg.: nearest 10 %).

Parameters

• azimuth_threshold (int) – Defines the incremental major orientation azimuth angle. Due to possible rounding errors, some surface azimuth can be rounded to values different than the main directions (eg.: 89 degrees instead of 90 degrees). Defaults to increments of 10 degrees.

• round_to (float) – Optionally round the WWR value to nearest value (eg.: nearest 10). If None, this is ignored and the float is returned.

Returns

A DataFrame with the total wall area, total window area and WWR for each main orientation of the building.

Return type

(pd.DataFrame)

space_heating_profile(units='kWh', energy_out_variable_name=None, name='Space Heating', EnergySeries_kwds=None)

Return space-heating time series.

Parameters

• units (str) – Units to convert the energy profile to. Will detect the units of the EnergyPlus results.

• energy_out_variable_name (list-like) – a list of EnergyPlus Variable names.

• name (str) – Name given to the EnergySeries.

• EnergySeries_kwds (dict, optional) – keywords passed to EnergySeries.from_sqlite()

Returns

EnergySeries

space_cooling_profile(units='kWh', energy_out_variable_name=None, name='Space Cooling', EnergySeries_kwds=None)

Return space-cooling time series.

Parameters

• units (str) – Units to convert the energy profile to. Will detect the units of the EnergyPlus results.

• energy_out_variable_name (list-like) – a list of EnergyPlus

• name (str) – Name given to the EnergySeries.

• EnergySeries_kwds (dict, optional) – keywords passed to EnergySeries.from_sqlite()

Returns

EnergySeries

service_water_heating_profile(units='kWh', energy_out_variable_name=None, name='Space Heating', EnergySeries_kwds=None)

Return service water heating (domestic hot water) time series.

Parameters

• units (str) – Units to convert the energy profile to. Will detect the units of the EnergyPlus results.

• energy_out_variable_name (list-like) – a list of EnergyPlus Variable names.

• name (str) – Name given to the EnergySeries.

• EnergySeries_kwds (dict, optional) – keywords passed to EnergySeries.from_sqlite()

Returns

EnergySeries

custom_profile(energy_out_variable_name, name, units='kWh', prep_outputs=None, EnergySeries_kwds=None)

Return user-defined time series.

Parameters

• energy_out_variable_name (list-like) – a list of EnergyPlus

• name (str) – Name given to the EnergySeries.

• units (str) – Units to convert the energy profile to. Will detect the units of the EnergyPlus results.

• prep_outputs –

• EnergySeries_kwds (dict, optional) – keywords passed to EnergySeries.from_sqlite()

Returns

EnergySeries

newidfobject(key, **kwargs) → Optional[geomeppy.patches.EpBunch]

Define EpBunch object and add to model.

The function will test if the object exists to prevent duplicates.

Parameters

• key (str) – The type of IDF object. This must be in ALL_CAPS.

• **kwargs – Keyword arguments in the format field=value used to set fields in the EnergyPlus object.

Example

>>> from archetypal import IDF
>>> IDF.newidfobject(
>>>     key="Schedule:Constant".upper(),
>>>     Name="AlwaysOn",
>>>     Schedule_Type_Limits_Name="",
>>>     Hourly_Value=1,
>>> )

Returns

the object, if successful None: If an error occured.

Return type

EpBunch

addidfobject(new_object) → geomeppy.patches.EpBunch

Add an IDF object to the model.

Parameters

new_object (EpBunch) – The IDF object to add.

Returns

object.

Return type

EpBunch

removeidfobject(idfobject)

Remove an IDF object from the model.

Parameters

idfobject (EpBunch) – The object to remove from the model.

removeidfobjects(idfobjects: Iterable[geomeppy.patches.EpBunch])

Remove an IDF object from the model.

Parameters

idfobjects – The object to remove from the model.

anidfobject(key: str, aname: str = '', **kwargs) → geomeppy.patches.EpBunch

Define and create an object, but don’t add it to the model.

See newidfobject()). If you don’t specify a value for a field, the default value will be set.

Example

>>> from archetypal import IDF
>>> IDF.anidfobject("CONSTRUCTION")
>>> IDF.anidfobject(
>>>     key="CONSTRUCTION",
>>>     Name='Interior Ceiling_class',
>>>     Outside_Layer='LW Concrete',
>>>     Layer_2='soundmat'
>>> )

Parameters

• key (str) – The type of IDF object. This must be in ALL_CAPS.

• aname (str) – This parameter is not used. It is left there for backward compatibility.

• kwargs – Keyword arguments in the format field=value used to set fields in the EnergyPlus object.

Returns

object.

Return type

EpBunch

get_schedule_type_limits_data_by_name(schedule_limit_name)

Return the data for a particular ‘ScheduleTypeLimits’ object.

Parameters

schedule_limit_name –

get_schedule_epbunch(name, sch_type=None)

Return the epbunch of a particular schedule name.

If the schedule type is known, retrievess it quicker.

Parameters

• name (str) – The name of the schedule to retreive in the IDF file.

• sch_type (str) – The schedule type, e.g.: “SCHEDULE:YEAR”.

property width

Get the width of the building [m].

property length

Get the length of the building [m].

resize(width, length)

Resize the floor plate to x and y [meters].

Parameters

• width (float) – The new width [m] of the building (x axis).

• length (float) – The new length [m] of the building (y axis).

rename(objkey, objname, newname)

Rename all the references to this objname.

Function comes from eppy.modeleditor and was modified to compare the name to rename with a lower string (see idfobject[idfobject.objls[findex]].lower() == objname.lower()).

Parameters

• objkey (str) – EpBunch we want to rename and rename all the occurrences where this object is in the IDF file

• objname (str) – The name of the EpBunch to rename

• newname (str) – New name used to rename the EpBunch

Returns

The renamed idf object

Return type

theobject (EpBunch)

set_wwr(wwr: Optional[float] = None, construction: Optional[str] = None, force: bool = False, wwr_map: Optional[dict] = None, orientation: Optional[str] = None, surfaces: Optional[Iterable] = None)

Set Window-to-Wall Ratio of external walls.

Different WWR can be applied to specific wall orientations using the wwr_map dictionary. This map is a dict of wwr values, keyed by wall.azimuth, which overrides the default passed as wwr. Note that wall.azimuth is rounded to the closest integer.

They can also be applied to walls oriented to a compass point, e.g. north, which will apply to walls which have an azimuth within 45 degrees of due north.

Parameters

• wwr – The window to wall ratio to apply to all orientations. If wwr_map is specified, wwr is the default wwr for oreintations not defined in the mapping.

• construction – Name of a window construction to apply.

• force – True to create windows on walls that don’t have any.

• wwr_map – Mapping from wall orientation (azimuth) to WWR, e.g. {180: 0.25, 90: 0.2}.

• orientation – One of “north”, “east”, “south”, “west”. Walls within 45 degrees will be affected.

• surfaces – Iterable of surfaces to set the window to wall ratio of.