translate

honeybee-energy translate

Commands for translating Honeybee Models files.

honeybee-energy translate [OPTIONS] COMMAND [ARGS]...

construction-sets-from-osm

Translate all ConstructionSets in an OpenStudio Model (OSM) to a Honeybee JSON.

The resulting JSON can be written into a user standards folder to add the constructions to a users standards library.

Args:
osm_file: Path to a OpenStudio Model (OSM) file.
honeybee-energy translate construction-sets-from-osm [OPTIONS] OSM_FILE

Options

--full, -a, --abridged

Flag to note whether the objects should be translated as an abridged specification instead of a specification that fully describes the object. This option should be used when the constructions-from-osm command will be used to separately translate all of the constructions from the OSM.

Default:

True

-i, --indent <indent>

Optional integer to specify the indentation in the output JSON file. Specifying an value here can produce more read-able JSONs.

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into the a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional JSON file to output the string of the translation. By default it printed out to stdout

Default:

'-'

Arguments

OSM_FILE

Required argument

constructions-from-idf

Translate a Construction IDF file to a honeybee JSON as an array of constructions.

Args:
construction_idf: Full path to a Construction IDF file. Only the constructions
and materials in this file will be extracted.
honeybee-energy translate constructions-from-idf [OPTIONS] CONSTRUCTION_IDF

Options

-i, --indent <indent>

Optional integer to specify the indentation in the output JSON file. Specifying an value here can produce more read-able JSONs.

-f, --output-file <output_file>

Optional JSON file to output the JSON string of the translation. By default this will be printed out to stdout

Default:

'-'

Arguments

CONSTRUCTION_IDF

Required argument

constructions-from-osm

Translate all Constructions in an OpenStudio Model (OSM) to a Honeybee JSON.

The resulting JSON can be written into a user standards folder to add the constructions to a users standards library.

Args:
osm_file: Path to a OpenStudio Model (OSM) file.
honeybee-energy translate constructions-from-osm [OPTIONS] OSM_FILE

Options

--full, -a, --abridged

Flag to note whether the objects should be translated as an abridged specification instead of a specification that fully describes the object. This option should be used when the materials-from-osm command will be used to separately translate all of the materials from the OSM.

Default:

True

-i, --indent <indent>

Optional integer to specify the indentation in the output JSON file. Specifying an value here can produce more read-able JSONs.

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into the a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional JSON file to output the string of the translation. By default it printed out to stdout

Default:

'-'

Arguments

OSM_FILE

Required argument

constructions-to-idf

Translate a Construction JSON file to an IDF using direct-to-idf translators.

Args:
construction_json: Full path to a Construction JSON file. This file should
either be an array of non-abridged Constructions or a dictionary where
the values are non-abridged Constructions.
honeybee-energy translate constructions-to-idf [OPTIONS] CONSTRUCTION_JSON

Options

-f, --output-file <output_file>

Optional IDF file to output the IDF string of the translation. By default this will be printed out to stdout

Default:

'-'

Arguments

CONSTRUCTION_JSON

Required argument

materials-from-osm

Translate all Materials in an OpenStudio Model (OSM) to a Honeybee JSON.

The resulting JSON can be written into a user standards folder to add the materials to a users standards library.

Args:
osm_file: Path to a OpenStudio Model (OSM) file.
honeybee-energy translate materials-from-osm [OPTIONS] OSM_FILE

Options

-i, --indent <indent>

Optional integer to specify the indentation in the output JSON file. Specifying an value here can produce more read-able JSONs.

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into the a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional JSON file to output the string of the translation. By default it printed out to stdout

Default:

'-'

Arguments

OSM_FILE

Required argument

model-from-gbxml

Translate a gbXML to a Honeybee Model (HBJSON).

Args:
gbxml_file: Path to a gbXML file.
honeybee-energy translate model-from-gbxml [OPTIONS] GBXML_FILE

Options

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into the a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional HBJSON file to output the string of the translation. By default it printed out to stdout

Arguments

GBXML_FILE

Required argument

model-from-idf

Translate an EnergyPlus Model (IDF) to a Honeybee Model (HBJSON).

Args:
idf_file: Path to an EnergyPlus Model (IDF) file.
honeybee-energy translate model-from-idf [OPTIONS] IDF_FILE

Options

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into the a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional HBJSON file to output the string of the translation. By default it printed out to stdout

Arguments

IDF_FILE

Required argument

model-from-osm

Translate a OpenStudio Model (OSM) to a Honeybee Model (HBJSON).

Args:
osm_file: Path to a OpenStudio Model (OSM) file.
honeybee-energy translate model-from-osm [OPTIONS] OSM_FILE

Options

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into the a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional HBJSON file to output the string of the translation. By default it printed out to stdout.

Arguments

OSM_FILE

Required argument

model-occ-schedules

Translate a Model’s occupancy schedules into a JSON of 0/1 values.

Args:
model_file: Full path to a Model JSON or Pkl file.
honeybee-energy translate model-occ-schedules [OPTIONS] MODEL_FILE

Options

-t, --threshold <threshold>

A number between 0 and 1 for the threshold at and above which a schedule value is considered occupied.

Default:

0.1

-p, --period <period>

An AnalysisPeriod string to dictate the start and end of the exported occupancy values (eg. “6/21 to 9/21 between 0 and 23 @1”). Note that the timestep of the period will determine the timestep of output values. If unspecified, the values will be annual.

-f, --output-file <output_file>

Optional file to output the JSON of occupancy values. By default this will be printed out to stdout

Default:

'-'

Arguments

MODEL_FILE

Required argument

model-to-gbxml

Translate a Honeybee Model (HBJSON) to a gbXML file.

Args:
model_file: Full path to a Honeybee Model file (HBJSON or HBpkl).
honeybee-energy translate model-to-gbxml [OPTIONS] MODEL_FILE

Options

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into a temp folder in the default simulation folder.

--default-subfaces, -t, --triangulate-subfaces

Flag to note whether sub-faces (including Apertures and Doors) should be triangulated if they have more than 4 sides (True) or whether they should be left as they are (False). This triangulation is necessary when exporting directly to EnergyPlus since it cannot accept sub-faces with more than 4 vertices.

Default:

True

--triangulate-non-planar, -np, --permit-non-planar

Flag to note whether any non-planar orphaned geometry in the model should be triangulated upon export. This can be helpful because OpenStudio simply raises an error when it encounters non-planar geometry, which would hinder the ability to save gbXML files that are to be corrected in other software.

Default:

True

--minimal, -fg, --full-geometry

Flag to note whether space boundaries and shell geometry should be included in the exported gbXML vs. just the minimal required non-manifold geometry.

Default:

True

-ift, --interior-face-type <interior_face_type>

Text string for the type to be used for all interior floor faces. If unspecified, the interior types will be left as they are. Choose from: InteriorFloor, Ceiling.

Default:

''

-gft, --ground-face-type <ground_face_type>

Text string for the type to be used for all ground-contact floor faces. If unspecified, the ground types will be left as they are. Choose from: UndergroundSlab, SlabOnGrade, RaisedFloor.

Default:

''

--check-model, -bc, --bypass-check

Flag to note whether the Model should be re-serialized to Python and checked before it is translated to .osm. The check is not needed if the model-json was exported directly from the honeybee-energy Python library.

Default:

True

-f, --output-file <output_file>

Optional gbXML file to output the string of the translation. By default it printed out to stdout

Arguments

MODEL_FILE

Required argument

model-to-idf

Translate a Model (HBJSON) file to a simplified IDF using direct-to-idf methods.

The direct-to-idf methods are faster than those that translate the model to OSM but certain features like detailed HVAC systems and the Airflow Network are not supported.

Args:

model_file: Full path to a Honeybee Model file (HBJSON or HBpkl).

honeybee-energy translate model-to-idf [OPTIONS] MODEL_FILE

Options

-sp, --sim-par-json <sim_par_json>

Full path to a honeybee energy SimulationParameter JSON that describes all of the settings for the simulation. If None default parameters will be generated.

-a, --additional-str <additional_str>

Text string for additional lines that should be added to the IDF.

Default:

''

--compact-schedules, -c, --csv-schedules

Flag to note whether any ScheduleFixedIntervals in the model should be included in the IDF string as a Schedule:Compact or they should be written as CSV Schedule:File and placed in a directory next to the output-file.

Default:

True

--hvac-to-ideal-air, -h, --hvac-check

Flag to note whether any detailed HVAC system templates should be converted to an equivalent IdealAirSystem upon export. If hvac-check is usedand the Model contains detailed systems, a ValueError will be raised.

Default:

True

--geometry-ids, -gn, --geometry-names

Flag to note whether a cleaned version of all geometry display names should be used instead of identifiers when translating the Model to IDF. Using this flag will affect all Rooms, Faces, Apertures, Doors, and Shades. It will generally result in more read-able names in the IDF but this means that it will not be easy to map the EnergyPlus results back to the original Honeybee Model. Cases of duplicate IDs resulting from non-unique names will be resolved by adding integers to the ends of the new IDs that are derived from the name.

Default:

True

--resource-ids, -rn, --resource-names

Flag to note whether a cleaned version of all resource display names should be used instead of identifiers when translating the Model to IDF. Using this flag will affect all Materials, Constructions, ConstructionSets, Schedules, Loads, and ProgramTypes. It will generally result in more read-able names for the resources in the IDF. Cases of duplicate IDs resulting from non-unique names will be resolved by adding integers to the ends of the new IDs that are derived from the name.

Default:

True

-f, --output-file <output_file>

Optional IDF file to output the IDF string of the translation. By default this will be printed out to stdout

Default:

'-'

Arguments

MODEL_FILE

Required argument

model-to-osm

Translate a Honeybee Model file into an OpenStudio Model and corresponding IDF.

Args:
model_file: Full path to a Honeybee Model file (HBJSON or HBpkl).
honeybee-energy translate model-to-osm [OPTIONS] MODEL_FILE

Options

-sp, --sim-par-json <sim_par_json>

Full path to a honeybee energy SimulationParameter JSON that describes all of the settings for the simulation. If None default parameters will be generated.

-epw, --epw-file <epw_file>

Full path to an EPW file to be associated with the exported OSM. This is typically not necessary but may be used when a sim-par-json is specified that requests a HVAC sizing calculation to be run as part of the translation process but no design days are inside this simulation parameter.

-f, --folder <folder>

Folder on this computer, into which the working files, OSM and IDF files will be written. If None, the files will be output in the same location as the model_file.

-osm, --osm-file <osm_file>

Optional path where the OSM will be copied after it is translated in the folder. If None, the file will not be copied.

-idf, --idf-file <idf_file>

Optional path where the IDF will be copied after it is translated in the folder. If None, the file will not be copied.

--geometry-ids, -gn, --geometry-names

Flag to note whether a cleaned version of all geometry display names should be used instead of identifiers when translating the Model to OSM and IDF. Using this flag will affect all Rooms, Faces, Apertures, Doors, and Shades. It will generally result in more read-able names in the OSM and IDF but this means that it will not be easy to map the EnergyPlus results back to the original Honeybee Model. Cases of duplicate IDs resulting from non-unique names will be resolved by adding integers to the ends of the new IDs that are derived from the name.

Default:

True

--resource-ids, -rn, --resource-names

Flag to note whether a cleaned version of all resource display names should be used instead of identifiers when translating the Model to OSM and IDF. Using this flag will affect all Materials, Constructions, ConstructionSets, Schedules, Loads, and ProgramTypes. It will generally result in more read-able names for the resources in the OSM and IDF. Cases of duplicate IDs resulting from non-unique names will be resolved by adding integers to the ends of the new IDs that are derived from the name.

Default:

True

--check-model, -bc, --bypass-check

Flag to note whether the Model should be re-serialized to Python and checked before it is translated to .osm. The check is not needed if the model-json was exported directly from the honeybee-energy Python library.

Default:

True

-log, --log-file <log_file>

Optional log file to output the paths to the generated OSM and IDF files if they were successfully created. By default this will be printed out to stdout.

Default:

'-'

Arguments

MODEL_FILE

Required argument

model-to-sdd

Translate a Honeybee Model file to a SDD file.

Args:
model_file: Full path to a Honeybee Model file (HBJSON or HBpkl).
honeybee-energy translate model-to-sdd [OPTIONS] MODEL_FILE

Options

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into a temp folder in the default simulation folder.

--check-model, -bc, --bypass-check

Flag to note whether the Model should be re-serialized to Python and checked before it is translated to .osm. The check is not needed if the model-json was exported directly from the honeybee-energy Python library.

Default:

True

-f, --output-file <output_file>

Optional SDD file to output the string of the translation. By default it printed out to stdout.

Arguments

MODEL_FILE

Required argument

model-to-trace-gbxml

Translate a Honeybee Model (HBJSON) to a gbXML file.

Args:
model_file: Full path to a Honeybee Model file (HBJSON or HBpkl).
honeybee-energy translate model-to-trace-gbxml [OPTIONS] MODEL_FILE

Options

--single-window, -fg, --detailed-windows

Flag to note whether all windows within walls should be converted to a single window with an area that matches the original geometry.

Default:

True

-r, --rect-sub-distance <rect_sub_distance>

A number for the resolution at which non-rectangular Apertures will be subdivided into smaller rectangular units. This is required as TRACE 3D plus cannot model non-rectangular geometries. This can include the units of the distance (eg. 0.5ft) or, if no units are provided, the value will be interpreted in the honeybee model units.

Default:

'0.15m'

-m, --frame-merge-distance <frame_merge_distance>

A number for the maximum distance between non-rectangular Apertures at which point the Apertures will be merged into a single rectangular geometry. This is often helpful when there are several triangular Apertures that together make a rectangle when they are merged across their frames. This can include the units of the distance (eg. 0.5ft) or, if no units are provided, the value will be interpreted in the honeybee model units

Default:

'0.2m'

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional gbXML file to output the string of the translation. By default it printed out to stdout.

Arguments

MODEL_FILE

Required argument

model-transmittance-schedules

Translate a Model’s shade transmittance schedules into a JSON of fractional vals.

Args:
model_file: Full path to a Model JSON or Pkl file.
honeybee-energy translate model-transmittance-schedules [OPTIONS] MODEL_FILE

Options

-p, --period <period>

An AnalysisPeriod string to dictate the start and end of the exported occupancy values (eg. “6/21 to 9/21 between 0 and 23 @1”). Note that the timestep of the period will determine the timestep of output values. If unspecified, the values will be annual.

-f, --output-file <output_file>

Optional file to output the JSON of occupancy values. By default this will be printed out to stdout

Default:

'-'

Arguments

MODEL_FILE

Required argument

programs-from-osm

Translate all ProgramTypes in an OpenStudio Model (OSM) to a Honeybee JSON.

The resulting JSON can be written into a user standards folder to add the programs to a users standards library.

Args:
osm_file: Path to a OpenStudio Model (OSM) file.
honeybee-energy translate programs-from-osm [OPTIONS] OSM_FILE

Options

--full, -a, --abridged

Flag to note whether the objects should be translated as an abridged specification instead of a specification that fully describes the object. This option should be used when the schedules-from-osm command will be used to separately translate all of the schedules from the OSM.

Default:

True

-i, --indent <indent>

Optional integer to specify the indentation in the output JSON file. Specifying an value here can produce more read-able JSONs.

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into the a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional JSON file to output the string of the translation. By default it printed out to stdout

Default:

'-'

Arguments

OSM_FILE

Required argument

schedule-type-limits-from-osm

Translate all ScheduleTypeLimits in an OpenStudio Model (OSM) to a Honeybee JSON.

The resulting JSON can be written into a user standards folder to add the type limits to a users standards library.

Args:
osm_file: Path to a OpenStudio Model (OSM) file.
honeybee-energy translate schedule-type-limits-from-osm [OPTIONS] OSM_FILE

Options

-i, --indent <indent>

Optional integer to specify the indentation in the output JSON file. Specifying an value here can produce more read-able JSONs.

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into the a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional JSON file to output the string of the translation. By default it printed out to stdout

Default:

'-'

Arguments

OSM_FILE

Required argument

schedules-from-idf

Translate a schedule IDF file to a honeybee JSON as an array of schedules.

Args:
schedule_idf: Full path to a Schedule IDF file. Only the schedules
and schedule type limits in this file will be extracted.
honeybee-energy translate schedules-from-idf [OPTIONS] SCHEDULE_IDF

Options

-i, --indent <indent>

Optional integer to specify the indentation in the output JSON file. Specifying an value here can produce more read-able JSONs.

-f, --output-file <output_file>

Optional JSON file to output the JSON string of the translation. By default this will be printed out to stdout

Default:

'-'

Arguments

SCHEDULE_IDF

Required argument

schedules-from-osm

Translate all Schedules in an OpenStudio Model (OSM) to a Honeybee JSON.

The resulting JSON can be written into a user standards folder to add the schedules to a users standards library.

Args:
osm_file: Path to a OpenStudio Model (OSM) file.
honeybee-energy translate schedules-from-osm [OPTIONS] OSM_FILE

Options

--full, -a, --abridged

Flag to note whether the objects should be translated as an abridged specification instead of a specification that fully describes the object. This option should be used when the schedule-type-limits-from-osm command will be used to separately translate all of the type limits from the OSM.

Default:

True

-i, --indent <indent>

Optional integer to specify the indentation in the output JSON file. Specifying an value here can produce more read-able JSONs.

-osw, --osw-folder <osw_folder>

Folder on this computer, into which the working files will be written. If None, it will be written into the a temp folder in the default simulation folder.

-f, --output-file <output_file>

Optional JSON file to output the string of the translation. By default it printed out to stdout

Default:

'-'

Arguments

OSM_FILE

Required argument

schedules-to-idf

Translate a Schedule JSON file to an IDF using direct-to-idf translators.

Args:
schedule_json: Full path to a Schedule JSON file. This file should
either be an array of non-abridged Schedules or a dictionary where
the values are non-abridged Schedules.
honeybee-energy translate schedules-to-idf [OPTIONS] SCHEDULE_JSON

Options

-f, --output-file <output_file>

Optional IDF file to output the IDF string of the translation. By default this will be printed out to stdout

Default:

'-'

Arguments

SCHEDULE_JSON

Required argument