IDF and JSON syntax¶

EnergyPlus has two different input file formats that can be used to describe the building and system that is simulated. The file extensions for the two formats are IDF and epJSON. For both input files, the numeric inputs are in SI units (International System of Units often called metric units).

IDF¶

The legacy file format is a text-based format that describes each input object in series. Each input object starts with the type of input object, and each value for each field follows in strict order separated by commas. The end of the input object is indicated by a semi-colon. Comments are indicated by an exclamation point "!" and anything after this is ignored by EnergyPlus. Commonly, an input object is spread over many lines in the file with one value for each field per line. The names of each field are not required but are usually shown after the value and the comma or semicolon as a special comment using "!-" as an indicator. The input objects can be in any order. An example of an input object in an IDF file is shown below:

Building,
  Simple One Zone,   !- Name
  0,                 !- North Axis {deg}
  Suburbs,           !- Terrain
  0.04,              !- Loads Convergence Tolerance Value
  0.004,             !- Temperature Convergence Tolerance Value {deltaC}
  MinimalShadowing,  !- Solar Distribution
  30,                !- Maximum Number of Warmup Days
  6;                 !- Minimum Number of Warmup Days

The details of this example input object are not important, but the use of commas, exclamation points, and the closing semi-colon are important. The IDF format is currently the most commonly used format throughout the EnergyPlus ecosystem of utilities and GUIs. The list of possible input objects and fields is documented in the Energy+.idd file.

A variation on the IDF file format is the IMF file format which includes macros that can be used for parametric analysis or file management called EP-Macros. To learn more about macros see the Input Macros chapter of the AuxiliaryPrograms document.

epJSON¶

A new file format based on the industry standard JSON format most often used to transmit data to and from web servers and web-browser based applications. It is a text-based file format. The JSON format has wide usage across many industries and is supported in just about every modern programming language. It is a field-value style format using brackets and colons to indicate the hierarchy and commas to separate each field and value pair. The input objects must appear grouped by the type of input object. The list of possible input objects and fields is documented in the Energy+.schema.epJSON file which uses json-schema. The same input object shown above in IDF format is shown below in epJSON format:

{
    "Building": {
        "Simple One Zone: {
            "idf_max_extensible_fields": 0,
            "idf_max_fields": 8,
            "idf_order": 3,
            "loads_convergence_tolerance_value": 0.04,
            "maximum_number_of_warmup_days": 30,
            "minimum_number_of_warmup_days": 6,
            "north_axis": 0,
            "solar_distribution": "MinimalShadowing",
            "temperature_convergence_tolerance_value": 0.004,
            "terrain": "Suburbs"
        }
    }
}

Converting between IDF and epJSON¶

While the IDF and epJSON file formats are quite different, they contain the same information, and either may be used. In general, if producing EnergyPlus input files using a programming language, the epJSON format might make more sense while, at this point, if producing IDF files using a GUI, they are likely to use the IDF format.

EnergyPlus, when used on the command line, can convert from IDF to epJSON and from epJSON to IDF using the -c or --convert option.

There is also a separate conversion utility ConvertInputFormat.exe in the root EnergyPlus folder. It takes the name of an IDF or epJSON input file (with extension) as an argument. For additional options, type

ConvertInputFormat --help.

when in the EnergyPlus folder. This will give the following display of options:

Usage: ConvertInputFormat [OPTIONS] input_file [input_file ..]
Options:
  -f, --format ARG                 Output format.
                                   Default means IDF->epJSON or epJSON->IDF
                                   Select one (case insensitive):
                                   default,idf,epjson,json,cbor,msgpack,ubjson,bson
  -h,   -help,   --help, --usage   Display usage instructions.
  -i, --input ARG                  Text file with list of input files to convert
                                   (newline delimited)
  -j ARG                           Number of threads
  -n, --noHVACTemplate             Do not convert HVACTemplate objects.
  -o, --output ARG                 Output directory. Will use input file
                                   location by default.
  -v, --version                    Display version information
Example: ConvertInputFormat in.idf

On Windows, you can also drag a file (IDF or epJSON) onto ConvertInputFormat.exe. Note that ConvertInputFormat is version-specific and will not convert an epJSON file that is not the same version.

There are three groups of special input objects which are preprocessor commands: GroundHeatTransfer:*, HVACTemplate:* Parametric:*. ConverInputFormat converts HVACTemplate objects. EnergyPlus does not convert any of these.