nelson

Documentation

Overview

Package nelson implements the Nelson (2000) dead fuel moisture model.

The model treats a dead fuel particle as a cylindrical stick with a set of radial nodes. It solves the coupled heat and moisture transfer between the stick and the air, so it needs the temperature, the relative humidity, the solar radiation, and the rainfall. It replaces the equilibrium moisture content method of the older NFDRS for the dead fuel time-lag classes (1-hour, 10-hour, 100-hour, and 1000-hour).

The code is ported from the firelab/NFDRS4 C++ program (deadfuelmoisture.cpp), which follows Nelson (2000) with the modifications of Bevins (2005).

References:

• Nelson, R.M. 2000. Prediction of diurnal change in 10-hr fuel stick moisture content. Canadian Journal of Forest Research 30:1071-1087.
• Bevins, C.D. 2005. dead fuel moisture model modifications, as coded in firelab/NFDRS4.

Index

• type State
  • func (s State) String() string
• type Stick
  • func NewStandardStick(tl TimeLag) *Stick
  • func (s *Stick) MedianRadialMoisture() firewx.Percent
  • func (s *Stick) MoistureContent() firewx.Percent
  • func (s *Stick) SurfaceMoisture() firewx.Percent
  • func (s *Stick) SurfaceTemperature() firewx.Celsius
  • func (s *Stick) Update(w Weather) bool
  • func (s *Stick) UpdateObs(o firewx.Obs, elapsed time.Duration) bool
• type TimeLag
• type Weather

Types

type State

type State int

State is the prevailing dead fuel moisture state after an update. The state names the physical process that governs the surface node during the step. The values match the DFM_State enumeration in firelab/NFDRS4.

const (
	StateNone State = iota
	StateAdsorption
	StateDesorption
	StateCondensation1
	StateCondensation2
	StateEvaporation
	StateRainfall1
	StateRainfall2
	StateRainstorm
	StateStagnation
	StateError
)

func (State) String

func (s State) String() string

String returns the name of the state.

type Stick

type Stick struct {
	SchemaVersion int    `json:"schema_version"`
	Name          string `json:"name"`

	// Fixed model parameters, set at construction.
	Radius          float64 `json:"radius"`           // stick radius (cm)
	Length          float64 `json:"length"`           // stick length (cm)
	Density         float64 `json:"density"`          // stick density (g/cm3)
	Nodes           int     `json:"nodes"`            // radial node count
	DSteps          int     `json:"d_steps"`          // diffusivity steps per observation
	MSteps          int     `json:"m_steps"`          // moisture steps per observation
	Hc              float64 `json:"hc"`               // planar heat transfer rate (cal/cm2-h-C)
	Rai0            float64 `json:"rai0"`             // rain runoff factor, first hour
	Rai1            float64 `json:"rai1"`             // rain runoff factor, later hours
	Stca            float64 `json:"stca"`             // adsorption mass transfer rate
	Stcd            float64 `json:"stcd"`             // desorption mass transfer rate
	Stv             float64 `json:"stv"`              // storm transition value (cm/h)
	Wfilmk          float64 `json:"wfilmk"`           // water film contribution (g/g)
	Wmx             float64 `json:"wmx"`              // maximum local moisture (g/g)
	AllowRainfall2  bool    `json:"allow_rainfall2"`  // apply Nelson later-hour runoff logic
	AllowRainstorm  bool    `json:"allow_rainstorm"`  // apply Nelson rainstorm logic
	PertubateColumn bool    `json:"pertubate_column"` // perturb continuous liquid columns
	RampRai0        bool    `json:"ramp_rai0"`        // ramp runoff after Bevins, not Nelson

	// Derived parameters, computed at construction.
	Dx   float64   `json:"dx"`   // internodal distance (cm)
	Dx2  float64   `json:"dx2"`  // two times Dx (cm)
	Wmax float64   `json:"wmax"` // maximum possible moisture (g/g)
	Amlf float64   `json:"amlf"` // evaporation and condensation factor
	Capf float64   `json:"capf"` // capillary factor
	Hwf  float64   `json:"hwf"`  // vapor diffusion factor
	Vf   float64   `json:"vf"`   // free water transport factor
	X    []float64 `json:"x"`    // nodal radial distances from centre (cm)
	V    []float64 `json:"v"`    // nodal volume fractions (dimensionless)

	// Previous observation.
	Ta0  float64 `json:"ta0"`  // air temperature (C)
	Ha0  float64 `json:"ha0"`  // air humidity (g/g)
	Sv0  float64 `json:"sv0"`  // solar radiation (mV)
	Rc0  float64 `json:"rc0"`  // cumulative rainfall (cm)
	Ra0  float64 `json:"ra0"`  // period rainfall (cm)
	Bp0  float64 `json:"bp0"`  // barometric pressure (cal/cm3)
	Init bool    `json:"init"` // environment initialized

	// Current observation.
	Ta1 float64 `json:"ta1"` // air temperature (C)
	Ha1 float64 `json:"ha1"` // air humidity (g/g)
	Sv1 float64 `json:"sv1"` // solar radiation (mV)
	Rc1 float64 `json:"rc1"` // cumulative rainfall (cm)
	Bp1 float64 `json:"bp1"` // barometric pressure (cal/cm3)
	Et  float64 `json:"et"`  // elapsed time since previous observation (h)

	// Time-step intermediates.
	Ddt     float64 `json:"ddt"`     // diffusivity time step (h)
	Mdt     float64 `json:"mdt"`     // moisture time step (h)
	Mdt2    float64 `json:"mdt2"`    // two times Mdt (h)
	Pptrate float64 `json:"pptrate"` // rainfall rate over Pi (cm/h)
	Ra1     float64 `json:"ra1"`     // period rainfall (cm)
	Rdur    float64 `json:"rdur"`    // rainfall duration (h)
	Sf      float64 `json:"sf"`      // Nelson "s" factor

	// Nodal state. These arrays must survive the JSON round trip exactly.
	T []float64 `json:"t"` // nodal temperatures (C)
	S []float64 `json:"s"` // nodal fiber saturation points (g/g)
	D []float64 `json:"d"` // nodal bound water diffusivities (cm2/h)
	W []float64 `json:"w"` // nodal moisture contents (g/g)

	// Surface and output intermediates.
	Hf      float64 `json:"hf"`      // stick surface humidity (g/g)
	Wsa     float64 `json:"wsa"`     // fiber saturation point (g/g)
	Sem     float64 `json:"sem"`     // equilibrium moisture content (g/g)
	Wfilm   float64 `json:"wfilm"`   // water film amount (g/g)
	Elapsed float64 `json:"elapsed"` // total simulation time (h)
	Updates int64   `json:"updates"` // number of updates
	State   State   `json:"state"`   // prevailing state
	// contains filtered or unexported fields
}

Stick is a stateful Nelson dead fuel moisture stick. It carries the full radial profile of temperature, moisture, and diffusivity between updates.

The exported fields hold the complete model state. A Stick marshals to JSON and back with an exact round trip, so a caller can persist the stick between runs and restore the radial nodes exactly. The unexported scratch slices are working buffers; each update overwrites them, so they need no persistence.

A Stick is not safe for concurrent use.

func NewStandardStick

func NewStandardStick(tl TimeLag) *Stick

NewStandardStick returns a stick for one of the four standard time-lag classes. The parameters follow the initDeadFuelMoisture factory methods in firelab/NFDRS4.

func (*Stick) MedianRadialMoisture

func (s *Stick) MedianRadialMoisture() firewx.Percent

MedianRadialMoisture returns the median moisture content of the radial nodes, as a percentage. This is the dead fuel moisture that the National Fire Danger Rating System uses, as medianRadialMoisture in firelab/NFDRS4 defines it.

func (*Stick) MoistureContent

func (s *Stick) MoistureContent() firewx.Percent

MoistureContent returns the mean moisture content of the radial profile. It uses Simpson's rule over the nodes, then adds the water film. This is the stick's fuel moisture, as meanMoisture in firelab/NFDRS4 defines it.

func (*Stick) SurfaceMoisture

func (s *Stick) SurfaceMoisture() firewx.Percent

SurfaceMoisture returns the moisture content of the surface node (g/g as a percentage).

func (*Stick) SurfaceTemperature

func (s *Stick) SurfaceTemperature() firewx.Celsius

SurfaceTemperature returns the temperature of the surface node. The National Fire Danger Rating System uses it as the fuel surface temperature for the ignition component.

func (*Stick) Update

func (s *Stick) Update(w Weather) bool

Update advances the stick by one weather observation. It returns false and leaves the stick unchanged if the observation is out of range. The precipitation is the amount since the previous observation.

Reference: this is a port of DeadFuelMoisture::update in firelab/NFDRS4, after Nelson (2000) with the modifications of Bevins (2005).

func (*Stick) UpdateObs

func (s *Stick) UpdateObs(o firewx.Obs, elapsed time.Duration) bool

UpdateObs advances the stick from a firewx.Obs over the elapsed time. The observation must carry temperature, relative humidity, solar radiation, and precipitation; an absent value leaves the stick unchanged and returns false. The precipitation is the amount since the previous observation.

type TimeLag

type TimeLag int

TimeLag is a standard dead fuel moisture time-lag class. The time lag is the time a stick needs to lose about two thirds of the difference between its moisture and the equilibrium moisture.

const (
	OneHour TimeLag = iota
	TenHour
	HundredHour
	ThousandHour
)

type Weather

type Weather struct {
	// Elapsed is the time since the previous observation.
	Elapsed time.Duration

	Temperature      firewx.Celsius
	RelativeHumidity firewx.Percent
	SolarRadiation   firewx.WattsPerSquareMeter

	// Rainfall is the precipitation amount since the previous observation.
	Rainfall firewx.Millimeters

	// Pressure is the barometric pressure. When it is absent, the model uses a
	// fixed default pressure, which matches firelab/NFDRS4.
	Pressure firewx.Opt[firewx.Hectopascals]
}

Weather is one weather observation for a Stick update. Every field has a named unit type. The rainfall is the amount since the previous observation, not the amount since midnight and not a rate.