Pioneering the design of materials for harnessing heat.

# Overview¶

WPTherml stands for **W**illiam **P**aterson University’s tool for
**Th**ermal **E**nergy and **R**adiation management with
**M**ulti **L**ayer nanostructures. The vision of this software
package is to provide an easy-to-use platform for the design of
materials with tailored optical and thermal properties for the vast
number of energy applications where control of absorption and emission
of radiation, or conversion of heat to radiation or vice versa, is
paramount. The optical properties are treated within classical
electrodynamics, and the current version uses the Transfer Matrix Method
to rigorously solve Maxwell’s equations for layered isotropic media.
WPTherml was conceived and developed by the Foley
Lab at William Paterson University. More
details of the Transfer Matrix equations, along will the full
mathematical formulation currently implemented in WPTherml, can be found
in the
documentation.

# Quick Start¶

- WPTherml is written in Python 3 and requires the numpy, scipy, and matplotlib packages. Current installation of the Anaconda Python 3 package should provide all you need on Windows, Mac, or Linux platforms
- To install from github:
`git clone https://github.com/FoleyLab/wptherml.git`

`cd wptherml`

`python3 setup.py install`

- To run unit tests from cloned repository:
`cd test`

`python3 -m pytest test.py`

- The test script for running unit tests can be downloaded here
- To install with pip:
`pip3 install wptherml`

- Open a new .py file in your favorite text editor or IDE, e.g.

`vim example.py`

The capabilities of this package are contained within a class called multilayer. A basic example of a script that imports the multilayer class, computes the reflectivity of 20 nm gold film coated with 50 nm of TiO2 and 100 nm SiO2, and plots it using pyplot follows:

```
from wptherml.wpml import multilayer
from matplotlib import pyplot as plt
### dictionary that stores basic properties
### of the multilayer structure you want to simulate
structure = {
### actual materials the structure is made from... note terminal layers are air and
### top-side layer (layer upon which light is incident) is SiO2.
### Refractive index values are stored in the attribute self.n
'Material_List': ['Air', 'SiO2', 'TiO2', 'Au', 'Air'],
### thickness of each layer... terminal layers must be set to zero
### values are stored in attribute self.d
'Thickness_List': [0, 100e-9, 50e-9, 20e-9, 0],
### range of wavelengths optical properties will be calculated for
### values are stored in the array self.lam
'Lambda_List': [400e-9, 800e-9, 1000]
}
### create the instance called coated_au_film
coated_au_film = multilayer(structure)
### create a plot of the reflectivity of the coated au film - use red lines
### the wavelengths are stored in SI units so we will multiply by 1e9 to
### plot them in nanometers
plt.plot(1e9*coated_au_film.lambda_array, coated_au_film.reflectivity_array, 'red')
plt.show()
```

{: .language-python}

- Save this script and run it either in the terminal as

`python3 example.py`

where example.py is the name of the file you created, or if you were doing this in an IDE, execute it within your IDE!

The schematic that illustrates the above example is shown in the figure below. Note the ordering of the layers in the picture and how they are specified through Material_List and Thickness_List relative to the incident, reflected, transmitted, and thermally-emitted light.

There are illustrative examples of using the features of the multilayer class contained in Jupyter notebooks within this repository, including:

- Validation of Basic Optical Properties
- Examples of Computing Basic Optical Properties
- Modeling Incandescent Sources
- Modeling Radiative Cooling Surfaces
- Video Demo for Radiative Cooling

More will be added in the near future!

# Playlist¶

The developers of WPTherml compiled a thematic Spotify Playlist called “Everything Thermal”; we hope it will inspire you to imagine new possibilities for harnessing heat and thermal radiation!

# Features List¶

- Computes Reflectivity, Transmissivity, and Absorptivity/Emissivity spectrum of arbitrary multi-layered planar structures using the Transfer Matrix Method
- Computes Thermal Emission spectrum at a given temperature of multi-layer structure as emissivity * Blackbody spectrum
- Computes solar power absorbed from absorptivity * AM1.5 spectrum
- From the quantities above, the following performance-related quantities can be computed for various thermal-related applications:

- Spectral Efficiency of (S)TPV Emitters for a given PV
- Useful Power Density (S)TPV Emitters for a given PV
- Short Circuit Current Density (S)TPV Emitter for a given PV
- TPV Efficiency (S)TPV Emitters for a given PV
- Absorber Efficiency for STPV Absorbers for a given concentration factor
- Luminous Efficiency/Luminous Efficacy of Incandescent bulb filaments
- Cooling Power for day-time radiative cooling for a given ambient temperature and temperature of the multi-layer

- From optical quantities, the following analysis can be performed

- Identify Surface Plasmon Polariton modes
- Identify Perfectly Absorbing modes
- Rendering of color of a multi-layer at cool temperatures and at elevated temperatures

The calculations of the quantities above are facilitated by a class
called *multilayer*. The *multilayer* class parses a dictionary for key
structural data like the material and thicknesses that comprise the
multi-layer structure being modeled, the types of applications one wants
to consider the multi-layer structure for. The following is the complete
list of dictionary keys the *multilayer* class will recognize, along
with the data the user can supply in association with each key:

```
'Lambda_List' # a list of three floats that includes in order (i) shortest wavelength in meters, (ii) longest wavelength in meters, and (iii) total number of wavelengths where you would like the optical quantities to be evaluated. (Default is [400e-9,6000e-9,1000])
'Thickness_List' # a list of floats that specify the thickness in meters of each layer. Note that the terminal layers (first and last) must have thickness of 0. (Default is [0, 900e-9, 0].)
'Material_List' # a list of strings that specify the materials in each layer (Default is ['Air', 'W', 'Air'].
The following strings are currently recognized for the following supported materials:
* 'Air' - keyword for Air
* 'SiO2' - keyword for Glass
* 'HfO2' - keyword for Hafnium Oxide
* 'Al2O3' - keyword for Aluminum Oxide
* 'TiO2' - keyword for Titanium Oxide
* 'AlN' - keyword for Aluminum Nitride
* 'TiN' - keyword for Titanium Nitride
* 'Ag' - keyword for Silver
* 'Au' - keyword for Gold
* 'Pd' - keyword for Palladium
* 'Pt' - keyword for Platinum
* 'W' - keyword for Tungsten
'Temperature' # a float specifying the temperature of the multi-layer structure in Kelvin. (Default is 300 K)
'PV_Temperature' # a float specifying the temperature of a PV cell in a (S)TPV device in Kelvin. (Default is 300 K).
'Ambient_Temperature' # a float specifying the ambient temperature in Kelvin for radiative cooling applications. (Default is 300 K).
'STPV_EMIT' # an int where '1' means compute properties associated with (S)TPV emitters. (Default is 0, do not compute these quantities).
'STPV_ABS' # an int where '1' means compute properties associated with STPV/Concentrated Solar absorbers. (Default is 0).
'COOLING' # an int where '1' means compute properties associated with radiative cooling. (Default is 0).
'LIGHTBULB' # an int where '1' means compute properties associated with incandescent sources. (Default is 0).
'COLOR' # an int where '1' means compute and display the ambient and thermal color of a structure. (Default is 0).
'EXPLICIT_ANGLE' # an int where '1' means compute the optical properties and thermal emission at a range of angles and, when applicable, compute performance properties with explicit angular dependence. (Default is 0, meaning most quantities will be computed assuming the emissivity does not depend upon angle.)
'DEG' # an int that specifies the number of different angles that will be considered
in the calculation of optical and thermal emission properties as a function of angle. (Default is 7, which has been observed to give reasonably good accuracy when all angular integrals are performed using Gauss-Legendre quadrature).
```

{: .language-python} ## Method and attribute list for multilayer class
Given the input parameters specified above, the *multilayer* class uses
different methods to compute properties relevant for thermal
applications, and those properties are stored as attributes of the
*multilayer* object. The following is a list of methods of the
*multilayer* class and their related attributes:

```python def inline_structure(structure): ### a method to parse
input parameters from a dictionary (here called structure, all
currently-supported dictionary ### keys are defined above. This method
is called by the **init** and defines the following attributes:

```
self.lambda_array # the list of wavelengths in meters that will be used to evaluate optical and thermal spectra
self.d # the list of thicknesses that define the geometry of the multilayer
self.matlist # the list of strings that specify the materials
self.n # the 2D arrays of refractive index values for each material for each wavelength (inner index specifies material, outter index wavelength)
self.T_ml # the temperature of the multi-layer in Kelvin
self.T_cell # the temperature of the PV cell in Kelvin
self.T_amb # the ambient temperature in Kelvin
self.stpv_emitter_calc # the flag that determines if (S)TPV emitter properties will be computed
self.stpv_absorber_calc # the flag that determines if (S)TPV absorber properties will be computed
self.cooling_calc # the flag that determines if radiative cooling properties will be computed
self.lightbulb_calc # the flag that determines if incandescent properties will be computed
self.color_calc # the flag that determines if colors will be rendered
self.explicit_angle # the flag that determines if explicit angle-dependence of optical properties will be considered
self.deg # the number of different angles that will be computed for angle-dependent optical properties
```

`{: .language-python} In addition to the attributes that are explicitly set by parsing user input, several more attributes that are arrays will be allocated based on attributes defined by inline_structure:`

python
### The following are always created self.reflectivity_array #
initialized as an array of zeros the same length as self.lambda_array
self.transmissivity_array # initialized as an array of zeros the same
length as self.lambda_array self.emissivity_array # initialized as an
array of zeros the same length as self.lambda_array
self.thermal_emission_array # initialized as an array of zeros the
same length as self.lambda_array

```
### The following are created if self.explicit_angle == 1
self.x # points from Gauss-Legendre grid of degree self.deg from 0 to 1
self.t # self.deg angles on Gauss-Legendre grid transformed to be between 0 and pi/2
self.w # self.deg weights from Gauss-Legendre grid transformed to be between 0 and pi/2
self.reflectivity_array_p # initialized as a 2D array of zeros, inner dimension same as self.deg and outter same as self.lambda_array
self.reflectivity_array_s # initialized as a 2D array of zeros, inner dimension same as self.deg and outter same as self.lambda_array
self.transmissivity_array_p # initialized as a 2D array of zeros, inner dimension same as self.deg and outter same as self.lambda_array
self.transmissivity_array_s # initialized as a 2D array of zeros, inner dimension same as self.deg and outter same as self.lambda_array
self.emissivity_array_p # initialized as a 2D array of zeros, inner dimension same as self.deg and outter same as self.lambda_array
self.emissivity_array_s # initialized as a 2D array of zeros, inner dimension same as self.deg and outter same as self.lambda_array
self.thermal_emission_array_p # initialized as a 2D array of zeros, inner dimension same as self.deg and outter same as self.lambda_array
self.thermal_emission_array_s # initialized as a 2D array of zeros, inner dimension same as self.deg and outter same as self.lambda_array
```

`{: .language-python}`

python ‘’’ Method to compute optical
properties of reflectivity, transmissivity, and emissivity of structure
as a function of wavelength assuming normal incidence ‘’’ def fresnel()

## Upon execution, the following arrays are filled with their respective values¶

## for every wavelength in self.lambda_array¶

self.reflectivity_array self.transmissivity_array
self.emissivity_array `{: .language-python}`

python ‘’’ Method to
compute optical properties of reflectivity, transmissivity, and
emissivity of structure as a function of wavelength and angle, both p-
and s-polarizations are considered ‘’’ def fresnel_ea()

## Upon execution, the following arrays are filled with their respective values¶

## for every wavelength in self.lambda_array and every angle in self.t¶

self.reflectivity_array_p self.reflectivity_array_s
self.transmissivity_array_p self.transmissivity_array_s
self.emissivity_array_p self.emissivity_array_s
`{: .language-python}`

python ‘’’ Method to compute thermal emission
spectrum of a structure at a given temperature; note temperature
specified by self.T_ml ‘’’ def thermal_emission()

## Upon execution, the following arrays are computed for every wavelength in self.lambda_array¶

## for temperature given by self.T_ml¶

self.BBs # Blackbody spectrum self.thermal_emission_array ## thermal emission of structure defined as Blackbody * emissivity ``` {: .language-python}

```
''' Method to compute thermal emission spectrum of a structure at a given temperature for a range of angles '''
def thermal_emission_ea()
### Upon execution, the following arrays are computed for every wavelength in self.lambda_array
### and every angle in self.t for temperature given by self.T_ml
self.thermal_emission_array_p ## thermal emission of structure defined as Blackbody * p-polarized emissivity
self.thermal_emission_array_s ## thermal emission of structure defined as Blackbody * s-polarized emissivity
```

{: .language-python}

```
''' Method to compute optical properties of reflectivity, transmissivity,
and emissivity as a function of angle for a given polarization self.pol and wavelength lambda_0 '''
def angular_fresnel(self, lambda_0)
### Upon execution, the following arrays are computed for 180 angles between 0 and pi/2
self.r_vs_theta # reflectivity
self.t_vs_theta # transmissivity
self.eps_vs_theta # emissivity
```

{: .language-python}

```
''' The following three methods compute figures of merit relevant for STPV emitters for a given
temperature self.T_ml, PV type self.PV and bandgap self.lbg, and PV temperature self.T_cell.
These methods assume the emissivity does not change with angle, and perform an analytic
integration over solid angles that make the computations much quicker, though also less realistic.'''
self.stpv_se() # compute the spectral efficiency and stores it in the attribute self.spectral_efficiency_val
self.stpv_pd() # computes the useful power density and stores it in the attribute self.power_density_val
self.stpv_etatpv() # computes the TPV emitter efficiency and stores it in the attribute self.tpv_efficiency_val
```

{: .language-python}

```
''' The following methods compute figures of merit relevant for STPV emitters for a given
temperature self.T_ml, PV type self.PV and bandgap self.lbg, and PV temperature self.T_cell.
These methods explicitly account for the angular dependence of the emissivity, making these calculations
more realistic but also more time consuming. '''
self.stpv_se_ea() # compute the spectral efficiency and stores it in the attribute self.spectral_efficiency_val
self.stpv_pd_ea() # computes the useful power density and stores it in the attribute self.power_density_val
self.stpv_etatpv_ea() # computes the TPV emitter efficiency and stores it in the attribute self.tpv_efficiency_val
```

{: .language-python}

```
''' The following methods compute the absorber efficiency of a STPV or concentrated solar absorber at a
given temperature self.T_ml '''
def stpv_etaabs_ea() # computes absorber efficiency and stores it in the attribute self.absorber_efficiency_val
```

{: .language-python}

```
''' method to render color of a structure from its thermal emission at a given temperature self.T_ml '''
def thermal_color()
''' method to render color of a structure from its reflection spectrum '''
def ambient_color()
''' method to render color in a +/- 5nm band around the wavelength lambda '''
def pure_color(lambda)
```

{: .language-python}

```
''' Method to compute the luminous efficiency of a structure at temperature self.T_ml.
Stores value to self.luminous_efficiency_val '''
def luminous_efficiency()
''' Method to compute the radiative cooling power of a structure at temperature self.T_ml in ambient
temperature self.T_amb while being illuminated by the AM1.5 spectrum. Upon execution, the relevant
values are stored to the attributes self.radiative_power_val (this is the flux that cools the structure),
self.atmospheric_power_val (part of flux that warms the structure) and self.solar_power_val (part of the flux
that warms the structure).'''
def cooling_power()
''' Method to add a layer to the structure; material of the layer to be added will be specified by 'material' argument
and thickness of the layer will be specified by the 'thickness' argument. The layer will be inserted after
the 'layer_number' layer. The method will also update spectral and performance quantities after the layer is
added; the instance name will be preserved after execution, so this is like a mutation operation.'''
def insert_layer(layer_number, material, thickness)
''' Method to extract the array of refractive index values associated with a specific layer; the method returns
this array. '''
def layer_ri(layer_number)
''' Method to define the refractive index of an existing layer (specified by layer_number) as an alloy
of material_1 and material_2 with a specified volume_fraction of material_1 in material_2 according
to either the Maxwell-Garnett or the Bruggeman effective medium theory. Using 'Bruggeman' as the
argument for model will use Bruggeman's effective medium theory, while any other string will default
to Maxwell-Garnett theory. Optical properties and performance figures are NOT updated upon execution of this method.'''
def layer_alloy(layer_number, volume_fraction, material_1, material_2, model)
''' Method to define the refractive index of an existing layer (specified by layer number) as a single
complex number (specified by refractive_index_value) for all wavelengths. Optical properties and performance figures are NOT updated upon execution of this method.'''
def layer_static_ri(layer_number, refractive_index_value)
''' Method to compute complex wavevector magnitude associated with the surface plasmon polariton mode on a given multi-layer
structure at a wavelength specified by the int wavelength_index, where self.lambda_array[wavelength_index] returns
the wavelength you are interested in in meters. Upon completion, the spp wavevector is stored in
self.spp_resonance_val '''
def find_spp(wavelength_index)
''' Method to compute complex wavevector magnitude associated with the perfectly absorbing mode on a given multi-layer
structure at a wavelength specified by the int wavelength_index, where self.lambda_array[wavelength_index] returns
the wavelength you are interested in in meters. Upon completion, the pa wavevector is stored in
self.pa_resonance_val '''
def find_pa()
```

{: .language-python}

# Extending the multilayer class¶

The multilayer class should provide a convenient mechanism for extension of the package to include additional applications (which might require different manipulations of the Fresnel quantities stored as the attributes self.reflectivity_array, self.emissivity_array, self.transmissivity_array, or the thermal emission stored as the attribute self.thermal_emission_array), or to include different classes of structures (non-planar structures, for example, where the same attributes self.reflectivity_array, etc., would be computed by a different method than the transfer matrix method). The typical workflow to extend the capabilities of the package could include

- Identifying any new properties that will be computed by the extension and adding appropriate attributes to the multilayer class
- Adding one or more functions to the libraries (stpvlib, etc.) that manipulates the Fresnel and/or thermal emission quantites as required to compute the new desired property
- Adding one or more multilayer methods to call the new library functions and store the resulting data in new or existing multilayer attributes as appropriate.