Angular redistribution matrix method

As described in the overview, the angular redistribution matrix method is used to couple the front and back surfaces and calculate reflection, absorption, transmission and absorption profiles through matrix multiplication. The key functions are process_structure and calculate_RAT.

rayflare.matrix_formalism.process_structure.process_structure(SC, options, save_location='default', overwrite=False)

Function which takes a list of Interface and BulkLayer objects, and user options, and carries out the necessary calculations to populate the redistribution matrices.

Parameters:

  • SC – list of Interface and BulkLayer objects. Order is [Interface, BulkLayer, Interface]

  • options – a dictionary or State object listing the user options

  • save_location –

    string - location where the calculated redistribution matrices should be stored. Currently recognized are:

    • ’default’, which stores the results in folder in your home directory called ‘RayFlare_results’

    • ’current’, which stores the results in the current working directory

    • or you can specify the full path location for wherever you want the results to be stored.

    In each case, the results will be stored in a subfolder with the name of the project (options.project_name)

  • overwrite – boolean - if True, will overwrite any existing results in the save_location. If False, will re-use any existing results (based on the project name, save_location and names of the surfaces) if they are available.

rayflare.matrix_formalism.multiply_matrices.append_per_pass_info(i1, vr, vt, a, vf_2, vb_1, Tb, Tf, Af, Ab)
rayflare.matrix_formalism.multiply_matrices.bulk_profile_calc(v_1, v_2, alphas, thetas, d, depths, A)
rayflare.matrix_formalism.multiply_matrices.calculate_RAT(SC, options, save_location='default')

After the list of Interface and BulkLayers has been processed by process_structure, this function calculates the R, A and T by calling matrix_multiplication.

Parameters:

  • SC – list of Interface and BulkLayer objects. Order is [Interface, BulkLayer, Interface]

  • options – options for the matrix calculations (State object or dictionary)

  • save_location –

    location from which to load the redistribution matrices. Current options:

    • ’default’, which stores the results in folder in your home directory called ‘RayFlare_results’

    • ’current’, which stores the results in the current working directory

    • or you can specify the full path location for wherever you want the results to be stored.

    This should match what was specified for process_structure.

Returns:

The number of returned values depends on whether absorption profiles were calculated or not. The first two are always returned, the final two are only returned if a calculation of absorption profiles was done.

  • RAT - an xarray with coordinates bulk_index and wl (wavelength), and 3 data variables: R (reflection), T (transmission) and A_bulk (absorption in the bulk medium. Currently, the bulk index can only be 0.

  • results_per_pass - a dictionary with entries ‘r’ (reflection), ‘t’ (transmission), ‘a’ (absorption in the surfaces) and ‘A’ (bulk absorption), which store these quantities per each pass of the bulk or interaction with the relevant surface during matrix multiplication. ‘r’, ‘t’ and ‘A’ are lists of length 1, corresponding to one set of values for each bulk material; the list entry is an array which is indexed as (pass number, wavelength). ‘a’ is a list of length two, corresponding to absorption in the front and back interface respectively. Each entry in the list is an array indexed as (pass number, wavelength, layer index).

  • profile - a list of xarrays, one for each surface. These store the absorption profiles and have coordinates wavelength and z (depth) position.

  • bulk_profile - a list of arrays, one for each bulk (currently, always only one). Indices are (wavelength, position)

rayflare.matrix_formalism.multiply_matrices.dot_wl(mat, vec)
rayflare.matrix_formalism.multiply_matrices.dot_wl_u2d(mat, vec)
rayflare.matrix_formalism.multiply_matrices.load_redistribution_matrices(results_path, n_a_in, n_interfaces, layer_names, front_or_rear, calc_prof_list=None)
rayflare.matrix_formalism.multiply_matrices.make_D(alphas, thick, thetas)

Makes the bulk absorption vector for the bulk material.

Parameters:

  • alphas – absorption coefficient (m^{-1})

  • thick – thickness of the slab in m

  • thetas – incident thetas in angle_vector (second column)

Returns:

rayflare.matrix_formalism.multiply_matrices.make_v0(th_in, phi_in, num_wl, n_theta_bins, c_azimuth, phi_sym, theta_spacing='sin')

This function makes the v0 array, corresponding to the input power per angular channel at each wavelength, of size (num_wl, n_angle_bins_in) where n_angle_bins in = len(angle_vector)/2

Parameters:

  • th_in – Polar angle of the incoming light (in radians)

  • phi_in – Azimuthal angle of the incoming light (in radians), or can be set as ‘all’ in which case the power is spread equally over all the phi bins for the relevant theta.

  • num_wl – Number of wavelengths

  • n_theta_bins – Number of theta bins in the matrix multiplication

  • c_azimuth – c_azimuth used to generate the matrices being multiplied

  • phi_sym – Defines symmetry element [0, phi_sym] into which values of phi can be collapsed (in radians)

Returns:

v0, an array of size (num_wl, n_angle_bins_in)

rayflare.matrix_formalism.multiply_matrices.matrix_multiplication(bulk_mats, bulk_thick, options, layer_names, calc_prof_list, save_location)
Parameters:

  • bulk_mats – list of bulk materials

  • bulk_thick – list of bulk thicknesses (in m)

  • options – user options (State object)

  • layer_names – list of names of the Interface layers, to load the redistribution matrices

  • calc_prof_list – list of lists - for each interface, which layers should be included in profile calculations (can be empty)

  • save_location – string, location of saved matrices

Returns:

Return type:

rayflare.matrix_formalism.multiply_matrices.out_to_in_matrix(phi_sym, angle_vector, theta_intv, phi_intv)
rayflare.matrix_formalism.ideal_cases.lambertian_matrix(angle_vector, theta_intv, surf_name, structpath, front_or_rear='front', save=True, overwrite=False)

Generates a redistribution matrix for perfect Lambertian reflection.

Parameters:

  • angle_vector – an angle_vector in the standard format

  • theta_intv – the theta (polar) intervals (edges of the bins) to be used

  • surf_name – surface name (for saving the matrix)

  • structpath – file path where matrices will be stored or loaded from

  • front_or_rear – generate matrix for ‘front’ or ‘rear’ incidence?

  • save – Boolean, whether to save the resulting matrix (True) or only return it (False). Default True

  • overwrite – Boolean, whether to overwrite existing saved matrices. Default False

Returns:

the redistribution matrix in sparse COO format.

rayflare.matrix_formalism.ideal_cases.mirror_matrix(angle_vector, theta_intv, phi_intv, surf_name, options, structpath, front_or_rear='front', save=True, overwrite=False)

Generates a redistribution matrix for a perfect mirror (100% reflection).

Parameters:

  • angle_vector – an angle_vector in the standard format

  • theta_intv – the theta (polar) intervals (edges of the bins) to be used

  • phi_intv – the phi (azimuthal) intervals (edges of the bins)

  • surf_name – surface name (for saving the matrix)

  • options – dictionary of user options

  • structpath – file path where matrices will be stored or loaded from

  • front_or_rear – generate matrix for ‘front’ or ‘rear’ incidence?

  • save – Boolean, whether to save the resulting matrix (True) or only return it (False). Default True

  • overwrite – Boolean, whether to overwrite existing saved matrices. Default False

Returns:

the redistribution matrix in sparse COO format.