Luminescence Sample Simulator:

MATLAB functions described in Brown, (2020)

A set of MATLAB functions to model how luminescence evolves in different geomorphic scenarios. Specifically, exposures to heat and sunlight can be simulated and the resulting signals shown. For a detailed description of the underlying luminescence rate equations, or to cite your use of these LuSS functions, please use Brown, (2020).

GUI described in Brown, (2025)

A graphical user interface (GUI) that incorporates some of the functions in Brown, (2020), as well as some additional features, such as simulating the history of multiple grains. For a full description of this GUI, or to cite your usage, please use Brown, (2025).

Table of Contents

1. MATLAB functions
   1. Three worked examples
   2. Functions to manipulate a sample
      1. Functions to initiate a sample
      2. Functions to expose a sample to the environment
   3. Functions to plot a sample's luminescence signal
   4. Other functions
2. LuSS GUI
   1. Installing LuSS GUI as MATLAB toolbox
   2. Installing LuSS GUI as standalone application
   3. GUI description
3. Reference

MATLAB functions

Three worked examples

Three worked examples are included to illustrate function usage. Example1.m simulates a quartz grain wandering across a landscape, experiencing sunlight, wildfire heat, burial, and stream residence. Example2.m simulates a feldspar grain within a cobble that exhumes and is exposed to sunlight, first on the ground surface and then beneath water. Example3.m simulates a rock exposed to wildfire heat.

Functions to manipulate a sample

After creating a sample as a data structure:

	sample=struct;

the functions listed below manipulate that sample.

Functions to initiate a sample

Function	Usage
makeSampleQuartz.m	Assign luminescence characteristics of quartz to sample.
makeSampleFeldspar.m	Assign luminescence characteristics of K-feldspar to sample.
makeSampleCobble.m	Adds depth to a sample. By default, a sample is defined as a grain, for which inward diffusion of light and heat is neglected.
makeCobbleIntoGrain.m	Removes depth from a sample. The luminescence signal from the outermost cobble shell is assigned to the grain.
fillTraps.m	Sets the fractional saturation (n/N) of the sample's luminescence signal to one. For cobbles, this applies to all depths.
emptyTraps.m	Sets the fractional saturation (n/N) to zero.

Functions to expose a sample to the environment

Function	Usage
sunlightExposure.m	Expose a cobble or grain to sunlight.
underwaterSunlightExposure.m	Expose a cobble or grain to sunlight attenuated by water.
darkGrainHeatExposure.m	Expose a grain to heat but not sunlight.
rateEqn.m	Expose a cobble or grain to heat or sunlight (with or without rock or water attenuation). This function is called by the previous three functions.

Functions to plot a sample's luminescence signal

Function	Usage
nN_t_plot.m	Plots fractional saturation (n/N) as a function of time. Use for grains.
nN_t_d_3dplot.m	Plots fractional saturation (n/N) as a function of time and cobble depth. Use for cobbles.
nN_final_t_plot.m	Plots fractional saturation (n/N) as a function of cobble depth at the final timestep. Use for cobbles.
appAge_t_plot.m	Plots apparent age (ka) as a function of time. Use for grains.
appAge_t_d_3dplot.m	Plots apparent age (ka) as a function of time and cobble depth. Use for cobbles.
appAge_final_t_plot.m	Plots apparent age (ka) as a function of cobble depth at the final timestep. Use for cobbles.

Other functions

All other functions included in the repository are dependencies that should be kept in the same directory as the other files, but will not ordinarily be directly used.

splinefit.m is copyright 2009, Jonas Lundgren. All rights reserved. Retrieved from MATLAB Central File Exchange in 2019.

zroots.m is modified from: Recktenwald, G., 2006. Transient, one-dimensional heat conduction in a convectively cooled sphere, Portland State University, Dept. of MME.

LuSS GUI

Installing LuSS GUI as MATLAB toolbox

Preferred option, but requires existing MATLAB license and installation

There are two options for installing this app. If the user has an existing MATLAB license, the app can simply be installed as an app within the MATLAB toolbox environment by downloading and opening the file titled LuSS_GUI_v1_4.mltbx. This is the recommended method, but it requires a MATLAB license, which may be cost-prohibitive for some.

Installing LuSS GUI as standalone application

For those without MATLAB license, but requires MATLAB Runtime installation (free)

Alternately, the user can install a standalone instance of the GUI. For this option, MATLAB Runtime must be installed first. This is a rather large download which can be found on the MathWorks website. For more information about the MATLAB Runtime and the MATLAB Runtime installer, see "Distribute Applications" in the MATLAB Compiler documentation in the MathWorks Documentation Center.

Once MATLAB Runtime is installed, the user can download and open the file titled LuSS_GUI_standalone_v1_4.exe to run the standalone GUI.

GUI description

For a detailed description of the LuSS GUI, including basic app functionality, a typical workflow, and three example applications, please see Brown, 2025.

Reference

[Brown, N.D., 2020.] Which geomorphic processes can be informed by luminescence measurements? Geomorphology 367, 107296. DOI: 10.1016/j.geomorph.2020.107296

[Brown, N.D., in review.] Introducing a MATLAB-based app for simulating luminescence sample histories. In review at Quaternary Research.