Neobem is a preprocessor programming language primarily targeted for the idf input files for EnergyPlus. It also supports the Building Description Language used for DOE-2.
You can download the entire user manual in PDF form here or view online at neobem.io.
Quick links:
While creating your building energy simulation input files, have you ever wanted to:
- Use variables?
- Break out sections into custom templates?
- Use arithmetic?
- Build objects directly from Excel or JSON data?
- Loop over lists?
- Easily incorporate work from others?
- Do all this without setting up a full Python, R, or Ruby working environment?
If so, Neobem is what you have always wanted.
At its core, Neobem is a command line application that follows the Unix principle of doing one thing and doing it well. That thing is compiling an expressive programming syntax into building energy simulation input.
It is a Unix filter program, taking input via standard input or a file and writing the results to standard output. It is designed to play one role in larger processing pipelines.
I hope you find it as useful as I do.
- Download program file from GitHub.
- Add directory location containing program file to
PATH
environment variable or symlink the executablenbem
to a location inPATH
. - Execute
nbem
in shell or command interpreter.
See below for additional details on these steps.
The latest release of Neobem is on GitHub, at https://github.com/mitchpaulus/neobem/releases. There you will see zips containing a compiled executable for various operating systems and CPU architectures.
- linux-arm64.zip
- linux-arm.zip
- linux-musl-x64.zip
- linux-x64.zip
- osx-x64.zip
- win-arm64.zip
- win-arm.zip
- win-x64.zip
- win-x86.zip
Download the zip file that matches your operating system and
architecture.1 For most people, this will be win-x64
, linux-x64
,
or osx-x64
.
The zip file will contain a single self contained executable. Extract that file from the zip file to a location that you will want the program to live. It doesn’t really matter where you put it, but recommended places would be:
C:\Program Files\neobem\neobem.exe
on Windows/usr/local/bin/nbem
or~/.local/bin/nbem
on Linux
Neobem is a console or command line application. It is meant to be run from a shell environment, that could be anything like2:
cmd.exe
or PowerShell on Windowsbash
,zsh
, orfish
running in any terminal emulator, such as:- Windows Terminal
- Terminal.app
- iTerm2
- Gnome Terminal
- Alacritty
- Konsole
- Terminator
Once the program files are installed in your preferred location, you
will want to add the folder to the PATH
environment variable (if the
location you put it in isn’t already there). Another option is to
symlink the executable to a location that is already in the PATH
variable. Here’s a
link
for creating symlinks in Windows, and another
link
for creating symlinks in Linux.
On Windows, you can get to the dialog box to change the PATH
variable
by doing a search for ‘Edit System Environment Variables’. There are
several biog posts on the Internet that can guide you through this with
screenshots, here are a curated few:
- https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/
- https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/
Here’s a post on Superuser answering the question, “What are PATH and other environment variables, and how can I set or use them?”
Setting the PATH
variable is most often done in the initialization of
the particular shell that you are using. The default shell on many
systems is bash
. To add a location to the PATH
every time bash is
invoked, you follow the steps
here.
You add the location to the existing PATH
variable in the
.bash_profile
or .bashrc
initialization file, making sure it is
exported.
If you are using a different shell, you already likely know how to add locations to the PATH, but for example the syntax for fish (the interactive shell I personally use), the syntax looks like:
set -gxp PATH "/path/to/directory"
The input files are simple text files - you can use any editor of choice to create them. Here’s a list of popular text editors that you might want to try. If you’ve never heard of a “text editor”, I’d begin with Visual Studio Code, Sublime Text, or Atom.
Cross-Platform:
Windows:
- Notepad++
- Notepad - yes, that Notepad built into Windows
Linux:
On Windows, the program is called nbem.exe
. On Linux and OSX, it is
just nbem
with no extension.
From the shell, you can test that things are working by running the command with the help argument like:
mp@mp-computer:~$ nbem -h
on Windows:
C:\Users\mpaulus> nbem.exe -h
If things are working correctly, you should see help text like:
mp@mp-computer:~$ nbem -h
USAGE: nbem [options..] [input file]
Compile Neobem file to EnergyPlus or DOE-2 input files.
With no [input file], input is read from file named 'in.nbem' in the
current directory. If the input file is '-', input is read from standard
input rather than from a file.
OPTIONS:
--doe2 Parse input file in DOE-2 Building Description Language format
-h, --help Show this help and exit
-f, --fmt Format file instead of compiling
-o, --output <filename> Output file name. Output is printed to standard output by default.
--tokens Print lexed tokens for debugging
--tree Print parse tree in Lisp format for debugging
-v, --version Print version number and exit
In general, you will call the execute the program nbem
, passing in
your Neobem input file as an argument.
To compile a Neobem file to an idf file, execute a command like
mp@mp-computer:~$ nbem in.nbem
where in.nbem
is the relative path to the file you want to compile. In
the example above, this would be the in.nbem
file in my home directory
(‘~
’). By default, the compiled output is printed to standard output,
which you will see on the screen. To put the output into a file, either
specify the file path as a option, or redirect the output in the shell.
Using Option:
mp@mp-computer:~$ nbem -o output.idf in.nbem
Using Redirection:
mp@mp-computer:~$ nbem in.nbem > output.idf
Please see this screencast
link that shows an example
workflow from start to finish. This particular workflow example used
bash
as the shell and the files were edited with Neovim.
If you believe you have come across a bug, please open a new GitHub issue. Please attempt to produce a “minimum reproducible example (MRE)” file that reproduces the problem. If the code snippet is small enough, include directly in the issue, otherwise attach the associated file.
You can also attempt to get support on Unmet
Hours, a site similar in spirit to
Stack Overflow, but for building energy
modelers. Make sure to tag the question with neobem
as I have an email
alert set up for those questions.
Feedback and contributions are welcomed. Small contributions can made directly in Pull Requests. If you’d like to propose a more significant or more fundamental change, I ask that it first be discussed to prevent wasted effort. Please use the “Discussions” within the GitHub repository, likely in the “General” or “Ideas” category.
If the change adds functionality, corresponding unit tests would be
expected. Tests are located in the test
project/directory.
For coding style conventions, you can follow the conventions laid out by Microsoft (link).
Building from source requires the following dependencies:
- A .NET environment. Typically installed with Visual Studio, Rider, or directly through the SDK libraries.
- ANTLR and Java. I typically use the open source version of Java at jdk.java.net.
- Optional: A
redo
. This is amake
alternative (see original description from Daniel J. Bernstein). There are several existing implementations out there. I now use theredo
fromzombiezen
and have usedapenwarr
s redo in the past. However, just to get things building, there is a minimaldo
shell executable in the root of the repository.
You can then follow along with the steps in the GitHub workflow that
tests building commits
(.github/workflows/dotnet.yml
).
The minimum steps after .NET and Java installation are:
# Get ANTLR (version 4.9.3 in this example)
curl --output antlr-4.9.3-complete.jar https://www.antlr.org/download/antlr-4.9.3-complete.jar
# Compile ANTLR grammars - environment variables ANTLR_JAR and CLASSPATH required.
export ANTLR_JAR="$(pwd)"/antlr-4.9.3-complete.jar
export CLASSPATH=.:"$(pwd)/antlr-4.9.3-complete.jar"
./do src/antlr/compiled
./do src/antlr/excelrange/compiled
./do src/antlr/idf/compiled
# Run redo targets
./do src/Help.cs src/Version.cs test/TestFileDirectory.cs
# Build
dotnet build src
dotnet build test