Arras Energy is a multi-purpose electric power system infrastructure modeling and simulation environment derived from DOE's GridLAB-D simulator and the California Energy Commission's HiPAS GridLAB-D infrastructure analysis system. For more information on DOE's GridLAB-D see https://www.gridlabd.org/. For more information on CEC's HiPAS GridLAB-D see https://github.com/slacgismo/hipas-gridlabd.

System Architecture

mermaid graph LR subgraph Inputs direction LR GLM input(JSON) Converters Geodata end Inputs --> gridlabd subgraph gridlabd engine <--> python engine <--> modules modules <--> python engine <--> shell python <--> shell subgraph modules climate loads generators solvers optimizers revenue reliability end end gridlabd --> Outputs subgraph Outputs output(JSON) CSV KML MySQL InfluxDB end gridlabd --> Subcommands subgraph Subcommands library template timezone marimo server end subgraph Tools loads assets schedules fire mapping markets end gridlabd <--> Tools

Quick start using Docker

The preferred method for running Arras Energy is to download the master image from docker hub (see https://hub.docker.com/repository/docker/lfenergy/arras/general). You must install the docker daemon to use docker images. See https://www.docker.com/get-started for details.

Once you have installed docker, you may issue the following commands to run GridLAB-D at the command line:

~~~ docker run -it -v $PWD:/model lfenergy/arras:latest gridlabd -W /model [LOADOPTIONS] [FILENAME.EXT] [RUNOPTIONS] ~~~

On many systems, an alias can be used to make this a simple command that resembles the command you would normally issue to run a host-based installation:

~~~ alias gridlabd='docker run -it -v $PWD:/tmp lfenergy/arras:latest gridlabd' ~~~

Note that this alias will interfere with any host-based installation. You may use the gridlabd docker command to manage the use of docker images concurrently with host-based installations.

Downloading pre-built images

Installation from downloads may require sudo priviledges and always requires curl. The install script will automatically download and install the latest production image for your system if you use the following command:

~~~ curl -sL http://install.arras.energy/install.sh | [sudo] sh ~~~

You can download the latest development image using the command:

~~~ curl -sL http://install-dev.arras.energy/install.sh | [sudo] sh ~~~

If you must use sudo, then don't forget to grant user permission to access the build and runtime virtual environments created by the installer, e.g.,

~~~ sudo chmod -R g+rwx ~root /usr/local sudo adduser $USER root ~~~

If you want to use a more secure approach to sharing the install among multiple users, see install/README.md.

The installer recognizes the following environment variables:

| Variable | Default | Description | -------- | ------- | ----------- | INSTALL_SOURCE | http://install.arras.energy | URL from which image is downloaded | INSTALL_TARGET | /usr/local/opt | Folder in which image is installed | INSTALL_STDERR | /dev/stderr | File to which error messages are sent | INSTALL_STDOUT | /dev/stdout | File to which output messages are sent | GRIDLABD_IMAGE | varies | Install image name, e.g., $OSNAME_$VERMAJOR-$MACHINE

This procedure may also be used in AWS EC2 instances and Docker containers.

If you have installed the AWS CLI, you can use the following command to get a list of available images:

~~~ aws s3 ls s3://install.arras.energy | grep tarz ~~~

Note that the installer only works with image name that conform to the name pattern VERSION-BUILD-BRANCH-SYSTEM-MACHINE.tarz.

Build from source

The prerequesites for building Arras Energy from source include git and curl. In general you can use the setup.sh script to verify and update your system so that the prerequesites are satisifed.

On most systems, the process is as follows:

~~~ git clone https://github.com/arras-energy/gridlabd cd gridlabd ./setup.sh --local ./build.sh --system --parallel --validate ~~~

If you want to clone an alternate repository, use the following git command instead:

~~~ git clone https://github.com/ORG/REPO gridlabd ~~~

If you do not specify the --local then by default the setup.sh source will match the git repository origin and branch if any. Otherwise the default source will be arras-energy/gridlabd/master. If you want to setup from a different origin, use the command export GRIDLABD_ORIGIN=ORG/REPO/BRANCH to specify an alternate source for setup.sh. The build.sh will also match the current git repository.

Do not run the setup.sh and build.sh scripts with sudo, as that will usually create a broken install. If necessary, you should give yourself permission to write /usr/local and brew's install folder. If you have not already done so, add brew to your path.

To upload the image to the AWS installer you must install the AWS CLI, and obtain credentials to access the installer's S3 buckets before using the command:

~~~ ./build.sh --upload ~~~

To make the image the latest release, use the command:

~~~ ./build.sh --release ~~~

When you are working in a master branch, these command will update install.arras.energy, otherwise the upload will go to install-dev.arras.energy.

Docker

Developers should use the following command to build GridLAB-D in a Docker container:

~~~ docker/build.sh ~~~

Note that Docker will build the currently checked out branch from the repository rather than from your local code.

To push the docker image to your personal Dockerhub, use the command:

~~~ docker/build.sh --push ~~~

The Dockerhub account is assumed to match the name of your GitHub account.

To release the docker image, use the command:

~~~ docker/build.sh --release ~~~

AWS EC2

The latest development and master builds of HiPAS gridlabd are available as community AMIs. Simply launch an ec2, browse the community AMIs and search for HiPAS Gridlabd

If you want to build gridlabd yourself, use the AWS Ubuntu AMI on AWS EC2 using the commands

~~~ git clone https://code.arras.energy/ [-b BRANCH] gridlabd cd gridlabd ./setup.sh --local ./build.sh --system --validate ~~~

The validation may take some time and it need not complete completely successfully for GridLAB-D to be used. The final report may look something like this:

~~~ Validation report: 747 models tested 1 unexpected errors 746 tests succeeded

99% success rate Total validation elapsed time: 281.9 seconds See '/HOME/USER/gridlabd/validate.txt' for details ERROR [build.sh]: unable to verify install ~~~

Windows WSL

GridLAB-D supports several WSL distributions, including the latest Ubuntu versions. See the setup folder for currently supported distributions.

Generally, running Arras Energy on Docker is preferred because it is usually faster. Building, running and installing Gridlabd in WSL is not that different from a normal linux installation. You can follow Microsoft's instructions on setting up WSL and adding/changing distro's here. These instructions work for both cases on supported operating systems, which you can find in the build-aux directory.

1) Open PowerShell as administrator or run the WSL (Ubuntu) from the start menu to open a dedicated terminal 2) Run wsl (Using Ubuntu) 3) Follow the Linux build procedure above.

Manual Build

You can build Arras Energy manually by running following commands in the top level repository folder:

1. Create the target folder:

~~~ mkdir -p /usr/local/opt/gridlabd ~~~

1. Activate the python build environment

~~~ . $HOME/.gridlabd/bin/activate ~~~

1. Create the configuration script

~~~ autoreconf -isf ~~~

1. Run the configuration script

~~~ ./configure ~~~

1. Compile everything

~~~ make ~~~

1. Install everything

~~~ make install ~~~

1. Validate the install

~~~ make validate ~~~

1. Release install to all users

~~~ make system ~~~

Pro Tips

1. If you accumulate a lot of local branches that no longer exist on the remote repo, you can use the following command to purge them:

~~~ host% git fetch -p && git branch -vv | awk '/: gone]/{print $1}' | xargs git branch -D ~~~

1. You can manage multiple installs using the gridlabd version command. See gridlabd version help for details

2. You can prevent ./configure using the configure cache by deleting the config.cache folder.

3. You can start a clean build using --clean option with ./build.sh. Note that this will delete any new files not added with git add.

4. You can change the install prefix using the --prefix FOLDER option with ./build.sh.

Citation

If you use this fork of GridLAB-D for a publication you are required to cite it, e.g.,

Chassin, D.P., et al., "GridLAB-D Version major.minor.patch-build (branch) platform", (year) [online]. Available at url, Accessed on: month day, year.

You may use the --cite command option to obtain the correct citation for your version:

~~~ host% gridlabd --cite Chassin, D.P., et al. "GridLAB-D 4.2.0-191008 (fixpythonvalidate) DARWIN", (2019) [online]. Available at https://source.arras.energy/commit/dfc392dc0208419ce9be0706f699fdd9a11e3f5b, Accessed on: Oct. 8, 2019. ~~~

This will allow anyone to identify the exact version you are using to obtain it from GitHub.

US Government Rights

This version of GridLAB-D is derived from the original US Department of Energy version of GridLAB-D developed at Pacific Northwest National Laboratory. The US Government retains certain rights as described in the original GridLAB-D license.

Contributions

Please see Arras Energy Contribution Policies for information on making contributions to this repository.