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.
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.gridlabd.us/install.sh | [sudo] sh
You can download the latest development image using the command:
curl -sL http://install-dev.gridlabd.us/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.gridlabd.us |
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.gridlabd.us | grep tarz
Note that the installer only works with image name that conform to the name pattern VERSION-BUILD-BRANCH-SYSTEM-MACHINE.tarz.
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://code.gridlabd.us/ [-b BRANCH] gridlabd
cd gridlabd
./setup.sh --local
./build.sh --system --validate
If you want to clone an alternate repository, use the following git command instead:
git clone https://github.com/ORG/REPO [-b BRANCH] 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.gridlabd.us, otherwise the upload will go to install-dev.gridlabd.us.
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
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.gridlabd.us/ [-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
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.
- Open PowerShell as administrator or run the WSL (Ubuntu) from the start menu to open a dedicated terminal
- Run
wsl(Using Ubuntu) - Follow the Linux build procedure above.
You can build Arras Energy manually by running following commands in the top level repository folder:
- Create the target folder:
mkdir -p /usr/local/opt/gridlabd
- Activate the python build environment
. $HOME/.gridlabd/bin/activate
- Create the configuration script
autoreconf -isf
- Run the configuration script
./configure
- Compile everything
make
- Install everything
make install
- Validate the install
make validate
- Release install to all users
make system
- 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
-
You can manage multiple installs using the
gridlabd versioncommand. Seegridlabd version helpfor details -
You can prevent
./configureusing the configure cache by deleting theconfig.cachefolder. -
You can start a clean build using
--cleanoption with./build.sh. Note that this will delete any new files not added withgit add. -
You can change the install prefix using the
--prefix FOLDERoption with./build.sh.
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 (fix_python_validate) DARWIN", (2019) [online]. Available at https://source.gridlabd.us/commit/dfc392dc0208419ce9be0706f699fdd9a11e3f5b, Accessed on: Oct. 8, 2019.
This will allow anyone to identify the exact version you are using to obtain it from GitHub.
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.
Please see Arras Energy Contribution Policies for information on making contributions to this repository.