epedit

README

EPEdit.go is a Go library for parsing, editing, and formatting EnergyPlus Input Data Files (.idf).

Features

• Parse IDF Files: Load .idf file content into a structured object model.
• Modify IDF: Create, update, or delete any object within the IDF model.
• Find IDF Objects: Easily find and retrieve objects by their type (e.g., Building, Material) and name.
• Modify Fields: Get and set values for any field of an IDF object.
• Export to IDF: Serialize the modified model back into a valid .idf file string.

Installation

go get github.com/chp-rubicell/EPEdit.go

Usage

See examples/readme_example/.

Import

import epedit "github.com/chp-rubicell/EPEdit.go"

Open IDD and IDF files

// Load the EnergyPlus IDD schema.
idd, err := epedit.ParseIDDFile("Energy+.idd")
if err != nil {
	log.Fatal(err)
}

// Load an existing IDF file using the parsed IDD.
idf, err := epedit.ParseIDFFile(idd, "input.idf")
if err != nil {
	log.Fatal(err)
}

Find and update objects

// Find an object by class name and object name.
building, err := idf.GetObjectByName("Building", "My Building")
if err != nil {
	log.Fatal(err)
}

// Update fields by their IDD field names.
if err := building.Set("North Axis", 0.0); err != nil {
	log.Fatal(err)
}
if err := building.Set("Terrain", "City"); err != nil {
	log.Fatal(err)
}

// Update multiple fields
err = building.Update(epedit.Fields{
	"Maximum Number of Warmup Days": 50,
	"Minimum Number of Warmup Days": 5,
})
if err != nil {
	log.Fatal(err)
}

fmt.Println(building)

Building,
    My Building,             !- Name
    0,                       !- North Axis {deg}
    City,                    !- Terrain
    0.0400,                  !- Loads Convergence Tolerance Value {W}
    0.2000,                  !- Temperature Convergence Tolerance Value {deltaC}
    FullInteriorAndExterior, !- Solar Distribution
    50,                      !- Maximum Number of Warmup Days
    5;                       !- Minimum Number of Warmup Days

Add new objects

// Add a new object with initial field values.
_, err = idf.AddObject("RunPeriod", epedit.Fields{
	"Name":                      "New Annual Run",
	"Begin Month":               1,
	"Begin Day of Month":        1,
	"End Month":                 12,
	"End Day of Month":          31,
	"Day of Week for Start Day": "Monday",
})
if err != nil {
	log.Fatal(err)
}

// Add a new object without default values.
_, err = idf.AddObject(
	"Material",
	epedit.Fields{
		"Name":          "New Insulation",
		"Thickness":     0.05,
		"Conductivity":  0.0314,
		"Density":       265,
		"Specific Heat": 836.8,
	},
	false,
)
if err != nil {
	log.Fatal(err)
}

Remove objects

// Remove an object
obj, err := idf.GetObjectByName("RunPeriod", "annual")
if err != nil {
	log.Fatal(err)
}
if err := idf.RemoveObject(obj); err != nil {
	log.Fatal(err)
}

Save IDF files

// Save the modified IDF file.
if err := idf.Save("output.idf"); err != nil {
	log.Fatal(err)
}

Related projects

    

License

Distributed under the MIT License.

Documentation

Index

• Variables
• func AnyToString(value any) string
• func GetContinuousDigitsIndices(name string) (startIndex int, endIndex int)
• func NewFormatConfig(classIndentSize int, fieldIndentSize int, fieldSize int) formatConfig
• type ClassDef
  • func (class *ClassDef) FindFieldIndex(fieldName string) (int, error)
  • func (class *ClassDef) GetFieldName(index int, addUnits bool) string
• type ExtPattern
• type ExtensibleDef
• type FieldDef
• type Fields
• type IDD
  • func NewIDD() *IDD
  • func ParseIDD(r io.Reader) (*IDD, error)
  • func ParseIDDFile(filename string) (*IDD, error)
• type IDF
  • func NewIDF(idd *IDD) *IDF
  • func ParseIDF(idd *IDD, r io.Reader) (*IDF, error)
  • func ParseIDFFile(idd *IDD, filename string) (*IDF, error)
  • func (idf *IDF) AddObject(className string, initialValues Fields, defaultValues ...bool) (*IDFObject, error)
  • func (idf *IDF) Format(cfg formatConfig) string
  • func (idf *IDF) GetObjectByName(className string, objectName string) (*IDFObject, error)
  • func (idf *IDF) GetObjects(className string) []*IDFObject
  • func (idf *IDF) RemoveObject(target *IDFObject) error
  • func (idf *IDF) Save(filename string, cfg ...formatConfig) error
  • func (idf *IDF) String() string
  • func (idf *IDF) WriteTo(w io.Writer) (int64, error)
• type IDFObject
  • func (obj *IDFObject) Format(cfg formatConfig) string
  • func (obj *IDFObject) GetFloat(fieldName string) float64
  • func (obj *IDFObject) GetFloatErr(fieldName string) (float64, error)
  • func (obj *IDFObject) GetInt(fieldName string) int
  • func (obj *IDFObject) GetIntErr(fieldName string) (int, error)
  • func (obj *IDFObject) GetString(fieldName string) string
  • func (obj *IDFObject) GetStringErr(fieldName string) (string, error)
  • func (obj *IDFObject) Set(fieldName string, value any) error
  • func (obj *IDFObject) SetByIndex(fieldIndex int, value any)
  • func (obj *IDFObject) String() string
  • func (obj *IDFObject) Update(values Fields) error
  • func (obj *IDFObject) WriteTo(w io.Writer) (int64, error)
• type Lexer
  • func NewLexer(r io.Reader, isIDD bool) *Lexer
  • func (l *Lexer) NextToken() Token
• type Token
• type TokenType

Variables

var MinimalFormatConfig = formatConfig{"", "", 0, true}

minimal format

Functions

func AnyToString

func AnyToString(value any) string

convert any type to string

func GetContinuousDigitsIndices

func GetContinuousDigitsIndices(name string) (startIndex int, endIndex int)

get start and end indices of continous digits (first appearance)

func NewFormatConfig

func NewFormatConfig(classIndentSize int, fieldIndentSize int, fieldSize int) formatConfig

generate formatConfig

Types

type ClassDef

type ClassDef struct {
	Name                string     // original name with capitalization
	Group               string     // \group
	Fields              []FieldDef // array of FieldDefs
	MinFields           int
	BaseFieldIndexMap   map[string]int // for fast indexing of fields (lowercase)
	Extensible          *ExtensibleDef // nil if empty
	FieldIdxWithDefault []int          // field indices with default value
}

IDD class definition (ex. Building, Zone)

func (*ClassDef) FindFieldIndex

func (class *ClassDef) FindFieldIndex(fieldName string) (int, error)

get index from field name (case-insensitive)

func (*ClassDef) GetFieldName

func (class *ClassDef) GetFieldName(index int, addUnits bool) string

get field name from index

type ExtPattern

type ExtPattern struct {
	Prefix       string
	Suffix       string
	SearchPrefix string // for searching (lowercase)
	SearchSuffix string // for searching (lowercase)
}

store extensible field names as Prefix + # + Suffix ex. "Vertex 1 X-coordinate" -> "Vertex ", " X-coordinate"

type ExtensibleDef

type ExtensibleDef struct {
	BeginIndex int // start index of the extensible fields
	Size       int // size of the extensible fields (ex. X, Y, Z coords -> 3)
	Patterns   []ExtPattern
}

IDD extensible field properties (used in ClassDef)

type FieldDef

type FieldDef struct {
	Name             string
	Required         bool
	Units            string
	Default          string
	Autosizable      bool
	Autocalculatable bool
	Type             string   // alpha, real, integer, choice, etc.
	Choices          []string // possible values for "\type choice"

}

IDD field definition (ex. Outside_Boundary_Condition)

type Fields

type Fields map[string]any // for ease of use for field input

type IDD

type IDD struct {
	Version        string
	Classes        map[string]*ClassDef // map for fast search (uppercase)
	OrderedClasses []*ClassDef          // for preserving order during export
}

IDD object that contains all of the definitions

func NewIDD

func NewIDD() *IDD

func ParseIDD

func ParseIDD(r io.Reader) (*IDD, error)

return pointer for parsed IDD struct using Lexer

func ParseIDDFile

func ParseIDDFile(filename string) (*IDD, error)

type IDF

type IDF struct {
	IDD     *IDD
	Objects map[string][]*IDFObject // CLASSNAME: IDFObject slice
}

func NewIDF

func NewIDF(idd *IDD) *IDF

func ParseIDF

func ParseIDF(idd *IDD, r io.Reader) (*IDF, error)

func ParseIDFFile

func ParseIDFFile(idd *IDD, filename string) (*IDF, error)

func (*IDF) AddObject

func (idf *IDF) AddObject(className string, initialValues Fields, defaultValues ...bool) (*IDFObject, error)

add object to IDF AddObject(..., false) to ignore default values

func (*IDF) Format

func (idf *IDF) Format(cfg formatConfig) string

convert IDF to string (for debugging)

func (*IDF) GetObjectByName

func (idf *IDF) GetObjectByName(className string, objectName string) (*IDFObject, error)

get object by first field (likely name)

func (*IDF) GetObjects

func (idf *IDF) GetObjects(className string) []*IDFObject

get object by class name

func (*IDF) RemoveObject

func (idf *IDF) RemoveObject(target *IDFObject) error

remove object from IDF

func (*IDF) Save

func (idf *IDF) Save(filename string, cfg ...formatConfig) error

func (*IDF) String

func (idf *IDF) String() string

convert IDFObject to string with default format config

func (*IDF) WriteTo

func (idf *IDF) WriteTo(w io.Writer) (int64, error)

write IDF to io.Writer

type IDFObject

type IDFObject struct {
	Class  *ClassDef
	Values []string // field values as slices
}

func (*IDFObject) Format

func (obj *IDFObject) Format(cfg formatConfig) string

convert IDFObject to string (for debugging)

func (*IDFObject) GetFloat

func (obj *IDFObject) GetFloat(fieldName string) float64

get value of field as float (case-insensitive, ignores error). math.NaN() if empty

func (*IDFObject) GetFloatErr

func (obj *IDFObject) GetFloatErr(fieldName string) (float64, error)

get value of field as float (case-insensitive, also returns error). math.NaN() if empty

func (*IDFObject) GetInt

func (obj *IDFObject) GetInt(fieldName string) int

get value of field as int (case-insensitive, ignores error). -1 if empty

func (*IDFObject) GetIntErr

func (obj *IDFObject) GetIntErr(fieldName string) (int, error)

get value of field as int (case-insensitive, also returns error). -1 if empty

func (*IDFObject) GetString

func (obj *IDFObject) GetString(fieldName string) string

get value of field as string (case-insensitive, ignores error). "" if empty

func (*IDFObject) GetStringErr

func (obj *IDFObject) GetStringErr(fieldName string) (string, error)

get value of field as string (case-insensitive, also returns error). "" if empty

func (*IDFObject) Set

func (obj *IDFObject) Set(fieldName string, value any) error

set value of field (case-insensitive)

func (*IDFObject) SetByIndex

func (obj *IDFObject) SetByIndex(fieldIndex int, value any)

set value of field using field index

func (*IDFObject) String

func (obj *IDFObject) String() string

convert IDFObject to string with default format config

func (*IDFObject) Update

func (obj *IDFObject) Update(values Fields) error

update object from map

func (*IDFObject) WriteTo

func (obj *IDFObject) WriteTo(w io.Writer) (int64, error)

write IDFObject to io.Writer

type Lexer

type Lexer struct {
	LineNum int  // current line number (for debugging)
	IsIDD   bool //  for IDD parsing
	// contains filtered or unexported fields
}

lexer

func NewLexer

func NewLexer(r io.Reader, isIDD bool) *Lexer

lexer constructor

func (*Lexer) NextToken

func (l *Lexer) NextToken() Token

return next token when parser requests

type Token

type Token struct {
	Type  TokenType
	Value string // if text, store real values, otherwise store ",", ";", etc.
}

smallest unit of meaning sent from lexer to parser

type TokenType

type TokenType int

Token type

const (
	TokenText      TokenType = iota // regular text (ex. Zone, \type)
	TokenComma                      // comma (,)
	TokenSemicolon                  // semicolon (;)
	TokenEOF                        // end of file
	TokenError                      // error
)