frads 0.3.0

Wrapper for Radiance related simulation workflows

 [](https://github.com/LBNL-ETA/frads/actions/workflows/python-publish.yml)  # _frads_: Framework for Radiance simulation control

This is the repository for _frads_ development. Radiance is a free and open-source, raytracing-based lighting engine that is used extensively by engineering firms for innovative solar control, lighting, and daylighting design to improve the energy efficiency of buildings. With matrix algebraic methods, climate-based annual simulations can now be conducted in less than two minutes. _frads_ automates setup of these simulations by providing end users with an open-source, high-level abstraction of the Radiance command-line workflow (Unix toolbox model), helping to reduce the steep learning curve and associated user errors. _frads_ also provides the necessary infrastructure needed for seamless integration of Radiance and other modeling tools, such as EnergyPlus.

[Documentation](https://lbnl-eta.github.io/frads/)

## Contact/ Support We welcome beta users of _frads_. Feel free to post questions and suggestions in the Discussion section of this GitHub site or contact the principal author at [e-mail]. Information about Radiance can be found at: https://www.radiance-online.org . The Radiance community is active and welcomes new users via the Radiance Discourse site or Unmet Hours.

## Testing _frads_ uses Radiance tools in its implementation. Radiance models have been rigorously tested and validated using laboratory and outdoor field data, demonstrating its superior performance in delivering photometrically accurate, photorealistic results. Each Radiance commit and release is tested using the GitHub Action system. Unit tests were developed for most of the major Radiance programs. Tests are performed using Radiance _radcompare_, which was designed specifically to test Monte Carlo ray-tracing algorithms. Integration tests are the main type of test performed for _frads_ commit and releases. These tests also use the GitHub Action system.

## Releases _frads_ is a work in progress (see to-do list below). _frads_ has been tested on the latest official release of Radiance (September 2020, v5.3) but may not have been tested on the latest HEAD release, which contains source code changes made as recently as yesterday. _frads_ has also been tested on the latest official EnergyPlus release (> v9.3).

## Installation

Before you can use frads, you need to install it.

### Install Python

Being a Python based library, you’ll need to install Python first. Python version 3.8 or newer is required for frads.

Get the latest version of Python at https://www.python.org/downloads/ or with your operating system’s package manager.

You can verify that Python is installed by typing python from your cmd/powershell/terminal; you should see something like:

$ python Python 3.X.X [GCC 4.x] on linux Type “help”, “copyright”, “credits” or “license” for more information. >>>

### Install frads

After you have Python installed, you should have pip command available in your shell environment as well. You can then use pip to install frads:

$ python -m pip install frads

Alternatively, more recent version of frads can be installed directly from github as well. Watch for the passing/failed tag on github to check if the current version passed the tests.:

$ python -m pip install git+https://github.com/LBNL-ETA/frads

### Verifying

To verify that frads can be seen by Python, type python from your shell. Then at the Python prompt, try to import frads

>>> import frads
>>> print(frads.__version__)
0.2.7

### Optional external library

Frads uses Python standard library for all of its functionalities. However, it will take advantage of [Numpy](https://numpy.org) if you have it installed. It will greatly accelerate the matrix multiplication process, especially for progressive simulation workflow.

The [gencolorsky](other_cli.md#gencolorsky) command line tool in frads also relies on [libRadTran](http://www.libradtran.org/) a radiative transfer library for computing the spectrally-resolved radiation data. You’d need to install it first to use [gencolorsky](other_cli.md#gencolorsky).

_frads_ runs from the terminal prompt (command line) on Windows, Mac, and Linux OS. Radiance must be [installed](https://www.radiance-online.org/download-install/radiance-source-code/latest-release) prior to use of _frads_. You can then install _frads_ by entering the following command in your terminal/cmd/powershell:

` pip install frads `

You can also install _frads_ from this Github repository using this command:

` pip install git+https://github.com/LBNL-ETA/frads.git `

## Reference

Wang, T., “Frads: A Python Library for Radiance Simulation Control”, 2021 Radiance workshop, Bilbao, Spain, August 19, 2021, [ppt](https://www.radiance-online.org/community/workshops/2021-bilbao-spain-2/presentations/19_thursday/frads.pdf) , [voice recording](https://www.radiance-online.org/community/workshops/2021-bilbao-spain-2)

Wang, T., Ward, G., and Lee, E.S. (2021), A Python Library for Radiance Matrix-based Simulation Control and EnergyPlus Integration, Proceedings of Building Simulation 2021, International Building Performance Simulation Association, Bruges, September 1-3, 2021. Publication to be posted: [pdf](https://www.researchgate.net/publication/358969936_A_Python_Library_for_Radiance_Matrix-based_Simulation_Control_and_EnergyPlus_Integration)

* License Agreement *

Framework for Radiance Simulation Control (Frads) Copyright (c) 2019, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

(1) Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

(2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

(3) Neither the name of the University of California, Lawrence Berkeley National Laboratory, U.S. Dept. of Energy nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

You are under no obligation whatsoever to provide any bug fixes, patches, or upgrades to the features, functionality or performance of the source code (“Enhancements”) to anyone; however, if you choose to make your Enhancements available either publicly, or directly to Lawrence Berkeley National Laboratory, without imposing a separate written license agreement for such Enhancements, then you hereby grant the following license: a non-exclusive, royalty-free perpetual license to install, use, modify, prepare derivative works, incorporate into other computer software, distribute, and sublicense such enhancements or derivative works thereof, in binary and source code form.