Skip to content

Weather#

The weather model computes the clock, the sun, the irradiance, the air, the wind, the clouds, the rain, the fog and the evaporation at ACRE. The soil water, the crops, the sensors and the sky of the game read its results.

Scope and Assumptions#

The model is the class AcresEnv::Model in AcresEnvironmentModel.cpp. It is an engine-free model. The class FAcresEnvironmentRuntime in AcresEnvironment.cpp loads the settings, steps the model and moves the sky of the game.

One step of the weather model: the clock, the rain schedule and the seeded generator drive eight calculations in a fixed sequence (sun, rain, clouds, irradiance, temperature and humidity, wind, fog and visibility, evaporation and surface film), the results go into one state snapshot, and the sky, the soil water, the crops, the sensors and the logs read the snapshot. One step of the weather model Drivers, from the settings Calculations, in this sequence Users of the state Clock start hour + scaled time Rain schedule window, total, manual rate Seeded generator SplitMix64, Box-Muller, 5 random processes Settings environment.json, then the -Env* options 1 Sun position NOAA series: elevation, azimuth, sunrise 2 Rain rate Beta(1.6, 3) storm shape, exact total 3 Clouds preset, convection, storm weight 4 Irradiance Haurwitz clear sky, cloud transmission 5 Temperature and humidity Parton-Logan curve, Magnus formula 6 Wind day mixing, gust front, log profile 7 Fog and visibility radiation fog, Koschmieder law 8 Evaporation and surface film Priestley-Taylor, 0.3 mm store State snapshot Sky and lights sun, exposure, clouds, fog, rain particles, work lights Soil water rain rate, evaporation, surface film Crops low and high temperature of the day Sensors LiDAR: rain and fog, cameras: the rendered sky Logs session log, episode log, HUD
One step of the weather model: the drivers, the sequence of calculations and the users of the state. Open the diagram
  • One state applies to the full tile. The weather does not change with the position.
  • The equations come from the publications in References. The default values are climate estimates for the middle of July. They are not station data.
  • A session has one rain event in its schedule. A manual rain rate can replace the schedule.
  • The same settings, the same seed and the same sequence of steps give the same weather.
  • The random processes use an exact update. The statistics do not change with the length of the step.
  • ACRES Core does not step the weather model. It keeps a constant soil-water condition for each episode.

Symbols#

Symbol Quantity Unit
\(t\) Simulated time from the start of the session s
\(H_c\) Clock: hours after local midnight of the start day h
\(h\) Local time of the day h
\(d\) Day index, 0 on the start day
\(n\) Day of the year
\(z\) Local time minus UTC h
\(\varphi, \lambda\) Latitude and longitude, east positive deg
\(\gamma\) Fractional year rad
\(E_t\) Equation of time min
\(\delta\) Solar declination rad
\(H\) Hour angle, 0 at solar noon deg
\(\alpha\) Sun elevation deg
\(A\) Sun azimuth, clockwise from north deg
\(G_{clear}, G\) Clear-sky irradiance and irradiance below the clouds, on a horizontal surface W/m²
\(N\) Cloud cover 0 to 1
\(W\) Storm weight 0 to 1
\(D\) Storm darkness 0 to 1
\(R\) Rain rate mm/h
\(P_{tot}, P_d\) Total of the rain event and rain that the model delivered mm
\(T, T_{dew}\) Air temperature and dew point °C
\(RH\) Relative humidity 0 to 1
\(U, U_g, U_c\) Wind speed at 10 m, gust speed, wind speed at 2.5 m m/s
\(V\) Visibility m
\(f\) Fog amount 0 to 1
\(R_n\) Net radiation at the surface W/m²
\(E\) Potential evaporation mm/h
\(X\) State of a random process
\(\xi\) Standard normal random number
\(S(a, b, x)\) Smooth step: \(q^2(3 - 2q)\) with \(q = \mathrm{clamp}((x-a)/(b-a), 0, 1)\)

The smooth step falls from 1 to 0 when \(a\) is larger than \(b\).

Clock and Time Scale#

The clock is one continuous number, \(H_c\). The value 26 is 02:00 on the second day. Model::Step computes it.

\[ H_c = h_0 + \frac{t}{3600}, \qquad d = \lfloor H_c / 24 \rfloor, \qquad h = H_c - 24\,d, \qquad n = n_0 + d \]

\(h_0\) is the start hour and \(n_0\) is the day of the year of the start date (DayOfYear, with leap years). The solar equations use \(((n - 1) \bmod 365) + 1\).

The setting seconds_per_game_minute gives the time scale \(k\), in simulated seconds for each real second.

\[ k = \frac{60}{s_{min}} \]

The value 60 gives real time. The value 1 gives a day in 24 minutes. The K key multiplies \(k\) by 600. The soil water and the crops use the same scale.

FAcresEnvironmentRuntime::Advance runs in each physics step of agent 0. It adds \(\Delta t_{physics}\,k\) to an accumulator. When the accumulator is 0.05 s or more, the model does one step with that time. At real time the model thus steps at 20 Hz. The game thread reads a copy of the state (Snapshot) one time for each frame.

Seeded Generators#

All random numbers come from one SplitMix64 generator. Model::Reset sets its state from the seed.

\[ s_0 = (\text{seed} \times \texttt{0x2545F4914F6CDD1D} + 1) \bmod 2^{64} \]

One output \(o\) is:

\[ \begin{aligned} s &\leftarrow (s + \texttt{0x9E3779B97F4A7C15}) \bmod 2^{64} \\ o &= s \oplus (s \gg 30), \quad o \leftarrow o \times \texttt{0xBF58476D1CE4E5B9} \\ o &\leftarrow o \oplus (o \gg 27), \quad o \leftarrow o \times \texttt{0x94D049BB133111EB} \\ o &\leftarrow o \oplus (o \gg 31) \end{aligned} \]

Model::Gauss makes one normal number from two outputs with the Box-Muller method.

\[ u_i = \frac{(o_i \gg 11) + 0.5}{2^{53}}, \qquad \xi = \sqrt{-2 \ln u_1}\,\cos(2\pi u_2) \]

Each random process is an Ornstein-Uhlenbeck process with the standard deviation \(\sigma\) and the time constant \(\tau\). Model::OU applies the exact update for a step \(\Delta t\).

\[ X \leftarrow X\,e^{-\Delta t/\tau} + \sigma \sqrt{1 - e^{-2\Delta t/\tau}}\;\xi \]
Process Time Constant Standard Deviation Use
\(X_{rain}\) 360 s 0.45 Logarithm of the factor on the rain rate
\(X_{cloud}\) 2700 s 0.08 Cloud cover
\(X_T\) 1800 s 0.35 °C Air temperature
\(X_w\) \(\max(20, 150/\max(0.5, \bar U))\) s Turbulence intensity Relative wind speed
\(X_{dir}\) 1200 s 18° Wind direction

A step with \(\Delta t = 0\) uses \(\Delta t = 0.001\) s in the update. One step draws the numbers in this sequence: day values, rain, clouds, temperature, wind speed, wind direction. The model keeps the values of the current day and the next day, and draws day values only for a new day. It draws the rain number only in the rain window.

Sun Position#

SolarPosition uses the NOAA series with the UTC hour \(h_{utc} = h - z\).

\[ \gamma = \frac{2\pi}{365}\left(n - 1 + \frac{h_{utc} - 12}{24}\right) \]
\[ E_t = 229.18\,(0.000075 + 0.001868\cos\gamma - 0.032077\sin\gamma - 0.014615\cos 2\gamma - 0.040849\sin 2\gamma) \]
\[ \begin{aligned} \delta = {} & 0.006918 - 0.399912\cos\gamma + 0.070257\sin\gamma - 0.006758\cos 2\gamma \\ & + 0.000907\sin 2\gamma - 0.002697\cos 3\gamma + 0.00148\sin 3\gamma \end{aligned} \]

The true solar time \(t_{sol}\) is in minutes.

\[ t_{sol} = 60\,h + E_t + 4\lambda - 60\,z, \qquad H = \frac{t_{sol}}{4} - 180 \]
\[ \cos Z = \sin\varphi \sin\delta + \cos\varphi \cos\delta \cos H, \qquad \alpha = 90 - Z \]
\[ A = \left(\operatorname{atan2}(\sin H,\; \cos H \sin\varphi - \tan\delta \cos\varphi) + 180\right) \bmod 360 \]

The elevation is geometric. It has no correction for refraction.

SunriseSunset computes \(E_t\) and \(\delta\) one time at 12:00 local time. It uses the zenith angle 90.833°.

\[ \cos H_0 = \mathrm{clamp}\!\left(\frac{\cos 90.833^\circ}{\cos\varphi \cos\delta} - \tan\varphi \tan\delta,\; -1,\; 1\right) \]
\[ h_{rise} = \frac{720 - 4(\lambda + H_0) - E_t}{60} + z, \qquad h_{set} = \frac{720 - 4(\lambda - H_0) - E_t}{60} + z \]

At ACRE on 15 July the functions give sunrise at 06:30 and sunset at 21:18. The largest elevation is 71.2° at 13:54.

Irradiance#

ClearSkyGhi is the equation of Haurwitz. The result is zero when the sun is below the horizon.

\[ G_{clear} = 1098\,\sin\alpha\; e^{-0.057/\sin\alpha} \]

CloudTransmission is the equation of Kasten and Czeplak with the cloud cover as a fraction. Model::Step adds a factor for the storm darkness.

\[ G = G_{clear}\,(1 - 0.75\,N^{3.4})\,(1 - 0.5\,D) \]

A full cloud cover transmits 25 % of the clear-sky irradiance. A full storm transmits half of that.

Clouds and Storm Weight#

Each cloud preset gives a base cover \(N_b\).

Preset Base Cover
clear 0.04
fair 0.25
partly 0.50
overcast 0.93

In the afternoon, convection adds cover. The preset overcast has no such term. \(T_{high}\) is the setting high_c.

\[ N_{conv} = 0.2\; S(11, 15, h)\,\bigl(1 - S(18, 21, h)\bigr)\, S(18, 28, T_{high}) \]

The storm weight \(W\) uses the hours until the rain starts, \(t_r = H_{start} - H_c\), and the hours after the end, \(t_e = H_c - H_{end}\).

\[ W = \begin{cases} 1 - S(0, 1.5, t_r) & t_r > 0 \\ 1 & t_r \le 0 \text{ and } t_e < 0 \\ e^{-t_e / 1.5} & t_e \ge 0 \end{cases} \]

A session without scheduled rain has \(W = 0\). With a manual rain rate, \(W\) is 1 when the rate is positive and 0 when the rate is zero.

\[ N = \mathrm{clamp}\Bigl(\mathrm{clamp}(N_b + N_{conv}, 0, 1)\,(1 - W) + 0.97\,W + X_{cloud}\,(1 - W),\; 0,\; 1\Bigr) \]

The storm darkness \(D\) makes a storm darker than an overcast sky. \(R_f\) is 10 mm/h in the last half hour before the rain and 0 at other times.

\[ D = \mathrm{clamp}\Bigl(W\,\bigl(0.35 + 0.65\,S(0, 20, R + R_f)\bigr),\; 0,\; 1\Bigr) \]

Temperature and Humidity#

Low and High of Each Day#

Day 0 uses the settings low_c and high_c. Model::EnsureDays draws the values of each subsequent day with two normal numbers. \(\sigma_d\) is the setting day_to_day_sigma_c.

\[ T_{min,d} = T_{low} + \sigma_d\,\xi_1 + 0.35\,\sigma_d\,\xi_2, \qquad T_{max,d} = \max(T_{min,d} + 1,\; T_{high} + \sigma_d\,\xi_1) \]

Daily Curve#

DiurnalTemperature is the model of Parton and Logan with \(a = 1.86\) h, \(b = 2.2\) and \(c = -0.17\) h. The day length is \(L_d = h_{set} - h_{rise}\). The night length is \(L_n = 24 - L_d\). The minimum occurs at \(h_{min} = h_{rise} + c\).

From \(h_{min}\) to \(h_{set}\):

\[ T_{PL}(h) = T_{min} + (T_{max} - T_{min})\,\sin\!\left(\frac{\pi\,(h - h_{min})}{L_d + 2a}\right) \]

At night, \(m\) is the number of hours after sunset and \(T_{set} = T_{PL}(h_{set})\). After sunset, \(T_l\) is the minimum of the next day. Before \(h_{min}\), \(T_l\) is the minimum of the current day.

\[ T_{PL} = T_l + (T_{set} - T_l)\,e^{-b\,m/L_n} - (T_{set} - T_l)\,e^{-b}\,\frac{m}{L_n} \]

Clouds, Rain and Noise#

Clouds decrease the daily range around the mean \(T_{mid} = (T_{min} + T_{max})/2\).

\[ T = T_{mid} + (T_{PL} - T_{mid})\,(1 - 0.45\,N) + X_T \]

The base dew point is \(T_{d0} = T_{min} - 0.8\). Rain moves the air temperature to \(T_{min}\). \(F_r\) is 1 in the rain window and when the manual rate is positive. It is 0 at other times.

\[ w = \mathrm{clamp}(R/4, 0, 1), \qquad q = 0.7\,w\,F_r + 0.3\,W\,(1 - F_r) \]
\[ T_{air} = T + (T_{d0} + 0.8 - T)\,q, \qquad T_{dew} = \min(T_{air},\; T_{d0} + 2.5\,W) \]

RelativeHumidity uses the Magnus formula with the coefficients of Alduchov and Eskridge.

\[ RH = \mathrm{clamp}\!\left(\frac{e(\min(T_{dew}, T_{air}))}{e(T_{air})},\, 0,\, 1\right), \qquad e(T) = \exp\!\left(\frac{17.625\,T}{243.04 + T}\right) \]

Wind#

The setting speed_mps is the mean wind at 10 m in the day. At night the mean is 65 % of it. A gust front increases the mean before scheduled rain. Its peak is 0.1 h before the start of the rain.

\[ m_d = 0.65 + 0.35\,S(-2, 25, \alpha), \qquad g = 1 + 0.9\,\exp\!\left(-\left(\frac{H_c - H_{start} + 0.1}{0.25}\right)^{2}\right) \]
\[ \bar U = \max(0, U_{set})\; m_d\; g \]

Without scheduled rain, \(g = 1\). The turbulence, the gust and the direction are:

\[ U = \max\bigl(0,\; \bar U\,(1 + X_w)\bigr), \qquad U_g = U\,(1 + 2.4\,I), \qquad \theta = (\theta_{set} + X_{dir} + 360) \bmod 360 \]

\(I\) is the setting turbulence_intensity. The wind at 2.5 m uses the neutral logarithmic profile with the roughness length \(z_0\).

\[ U_c = U\,\frac{\ln(2.5 / z_0)}{\ln(10 / z_0)} \]

With \(z_0 = 0.03\) m the ratio is 0.761.

Rain#

Storm Shape#

A rain event has a window from \(H_{start}\) to \(H_{end}\) and a total \(P_{tot}\). The relative time is \(u = (H_c - H_{start})/(H_{end} - H_{start})\). RainPlanFraction gives the fraction of the total that falls until \(u\). The shape is a Beta(1.6, 3) distribution.

\[ F(u) = \frac{\int_0^u x^{0.6}\,(1 - x)^2\,dx}{\int_0^1 x^{0.6}\,(1 - x)^2\,dx} \]

The function integrates with the Simpson rule and 64 intervals. The rate has its peak at \(u = 0.23\). The values are \(F(0.25) = 0.367\), \(F(0.5) = 0.766\) and \(F(0.75) = 0.966\).

Rain Rate of a Step#

Model::Step computes the rate in six steps. All rates are in mm/h.

  1. The planned rate, for \(0 < u < 1\). The derivative is a difference between \(u^- = \max(0, u - 0.001)\) and \(u^+ = \min(1, u + 0.001)\).

    \[ R_p = \frac{P_{tot}}{H_{end} - H_{start}}\;\frac{F(u^+) - F(u^-)}{u^+ - u^-} \]
  2. The gust factor. The term \(-0.1\) removes the mean bias of the log-normal factor.

    \[ R = R_p\; e^{X_{rain} - 0.1} \]
  3. The correction of a deficit. When \(P_d < P_{tot} F(u)\), the model removes the deficit in 600 s.

    \[ R \leftarrow R + 6\,\bigl(P_{tot} F(u) - P_d\bigr) \]
  4. The scale to the remaining rain.

    \[ R \leftarrow R\;\mathrm{clamp}\!\left(\frac{P_{tot} - P_d}{\max(10^{-9},\; P_{tot} - P_{tot} F(u))},\; 0,\; 4\right) \]
  5. The booking. The model reports the rate that it booked.

    \[ P_d' = \min\!\left(P_{tot},\; P_d + \frac{R\,\Delta t}{3600}\right), \qquad R \leftarrow \frac{3600\,(P_d' - P_d)}{\Delta t} \]
  6. The end of the window. When \(u \ge 1\) and \(P_d < P_{tot}\), the model sets \(P_d = P_{tot}\). The rate is zero.

The integral of the reported rate is thus equal to the total. The soil-water model integrates that rate.

A check with the default seed used an event of 10 mm in 1 h. The integral was 10.0000 mm for steps of 0.05 s, 1 s, 10 s and 60 s. The peak of the plan is 18.4 mm/h. With gusts the peak rate was between 34 mm/h and 51 mm/h. The test program Tools/Terramechanics/physics_tests examines the total for three seeds and three step lengths.

Start in the Rain Window#

When the session starts in the window, Model::Reset sets \(P_d = P_{tot} F(u_0)\). That rain fell before the session. It does not go to the fields. The state RainPlannedMm contains only the remaining rain.

Use prior_mm and prior_hours to start with wet soil. The weather model ignores these two settings. Soil Water uses them.

Manual Rain#

A manual rate that is zero or more replaces the scheduled rate. The schedule continues in the background. The model books the scheduled rain of that time as skipped rain. Thus the schedule does not make a burst when it comes back. RainTotalMm is the scheduled rain that fell plus the manual rain.

Fog and Visibility#

The fog model gives radiation fog. The conditions are a small dew-point spread, low wind, no sun and an open sky.

\[ c_f = S(1.5, 0.5, T_{air} - T_{dew})\; S(3, 1, U)\; \bigl(1 - S(-1, 10, \alpha)\bigr)\; \bigl(1 - S(0.5, 0.8, N)\bigr) \]

In the mode auto the fog amount moves to \(c_f\) with a time constant \(\tau_f\).

\[ f \leftarrow f + (c_f - f)\,(1 - e^{-\Delta t / \tau_f}), \qquad \tau_f = \begin{cases} 1800\ \text{s} & c_f > f \\ 900\ \text{s} & c_f \le f \text{ and } \alpha > 5^\circ \\ 2400\ \text{s} & \text{other} \end{cases} \]

In the modes off and fixed, \(f = 0\).

The visibility follows the law of Koschmieder, \(V = 3.912/\sigma_e\). The extinction \(\sigma_e\) is the sum of three terms.

\[ V_{haze} = 30000\,(1 - 0.9\,RH)^{0.8}, \qquad V_{rain} = 11100\,R^{-0.63} \quad (R > 0.05) \]
\[ \sigma_e = \frac{3.912}{\max(V_{haze}, 500)} + \frac{3.912}{V_{rain}} + f\,\frac{3.912}{150} \]

The rain term is zero when \(R \le 0.05\) mm/h. Full fog alone gives 150 m. In the mode fixed, \(\sigma_e = 3.912 / \max(20, V_{fixed})\).

Evaporation and Surface Film#

The net radiation uses an albedo of 0.23 and a simple long-wave loss. The factor \(c_n\) is 1 when \(\alpha > 0\) and 0.8 at night.

\[ R_n = 0.77\,G - (70 - 45\,N)\,c_n \]

PriestleyTaylorMmH computes the potential evaporation with the constants of FAO-56.

\[ e_s = 0.6108\,\exp\!\left(\frac{17.27\,T}{T + 237.3}\right), \qquad \Delta = \frac{4098\,e_s}{(T + 237.3)^2} \]
\[ G_s = \begin{cases} 0.1\,R_n & R_n > 0 \\ 0.5\,R_n & R_n \le 0 \end{cases}, \qquad E = \max\!\left(0,\; 1.26\,\frac{\Delta}{\Delta + 0.0665}\,\frac{R_n - G_s}{2.45 \times 10^{6}} \times 3600\right) \]

\(e_s\) is in kPa and \(\Delta\) is in kPa/°C. The model sets \(E = 0\) while rain falls. The default day gives 6.9 mm of potential evaporation in 24 h.

The surface film is a store of 0.3 mm on the ground, the roofs and the leaves. Rain fills the store. Without rain the store dries at the rate \(E_f\).

\[ E_f = \max\bigl(0.02,\; E(\max(0, R_n) + 30,\; T_{air})\bigr) \]
\[ w_f \leftarrow \mathrm{clamp}\!\left(w_f + \frac{(R - E_f)\,\Delta t}{3600},\; 0,\; 0.3\right), \qquad \text{SurfaceWetness} = \frac{w_f}{0.3} \]

\(E_f\) is zero while rain falls.

What the Weather Drives#

User Values Effect
Soil Water RainMmH, EvaporationMmH × 24, the time scale Rain and evaporation of the water grid.
Tyres on soil SurfaceWetness The rain film makes the soil surface wet before the layer becomes wet. See Soil Water.
Crops DayLowC, DayHighC The degree-days of each field.
LiDAR RainMmH, VisibilityM Attenuation and rain returns. The sensor reads the state at the time of the scan.
Camera The rendered sky Sun, clouds, fog, rain streaks and drops on the lens.
Lights of the vehicle SunElevationDeg, StormDarkness, VisibilityM See below.
Crop and ground materials WindCropMps, GustMps, WindDirection, RainMmH, SurfaceWetness Plant motion and wet surfaces, through the material parameters MPC_AcresWeather.
Session Log Air temperature, rain, wind, cloud cover Columns of tractor.csv.
Episode Log The conditions The conditions message.

The lights come on when \(\alpha < 1.5^\circ\), \(D > 0.6\) or \(V < 400\) m. They go off when \(\alpha > 4^\circ\), \(D < 0.4\) and \(V > 700\) m.

FAcresEnvironmentRuntime::UpdateVisuals sets the sky in each frame. The values of the level are the base values.

Item Rule
Sun direction The sun vector from \(\alpha\) and \(A\). The update occurs when the direction changes by more than 0.02°.
Sun intensity Base value \(\times\; S(-3, 1.5, \alpha)\,(1 - 0.9\,D)\).
Exposure target \(EV = \mathrm{clamp}(\log_2(E_v / 2.5) - 1.3 - 1.1\,D,\; 4,\; 14.6)\) with \(E_v = 110\,G + 400\,S(-8, 2, \alpha) + 2\) lux.
Exposure band The centre moves 5 % to the target in each frame. The half width is \(0.35 + 2\,(1 - S(4, 25, \alpha))\) EV.
Cloud coverage Material parameter \(-0.65 + 1.6\,N\).
Cloud density \(0.04\,(1 + 2.5\,D + 0.8\,S(0.6, 1, N))\).
Cloud colour and layer The albedo goes from 1 to 0.28 with \(D\). The layer bottom goes to 0.7 km and the thickness to 6 km.
Fog density \(\min(0.6,\; 20 \times 3.912 / \max(20, V))\).
Rain particles On when \(R > 0.02\) mm/h. The drift velocity is 85 % of \(U\).

Changes during a Session#

Input Function Effect
J key ToggleRain Sets a manual rate of 20 mm/h in dry weather, or 0 mm/h in rain. A second press gives control back to the schedule.
K key ToggleFast Multiplies the time scale by 600. A second press removes the factor.
set_conditions, part clock SetClock Starts the model again at a date and an hour. All other settings stay.
set_conditions, part weather SetWeather Starts the model again at the current date and time with a preset.
Vehicle bridge, key env_clock SetClock The same as the part clock.

A new start resets the random processes from the seed. The preset of SetWeather removes the scheduled rain.

Preset Clouds Fog Manual Rain
clear clear off 0 mm/h
fair fair auto 0 mm/h
overcast overcast auto 0 mm/h
rain overcast auto 8 mm/h
storm overcast auto 30 mm/h
fog overcast fixed, 300 m 0 mm/h

A rain rate of zero or more in the request replaces the rate of the preset. A request without a preset changes only the manual rain rate. A negative rate then gives control back to the schedule. Simulator Control Channel gives the format of the request.

Weather Replay Files#

A weather replay file is an environment file for one real day at ACRE. The folder Calibration/Weather/Replay contains 33 files with the name env_<date>.json. The script Calibration/Weather/ground_conditions.py writes them from the record of the Purdue Mesonet station ACRE.

Setting Source in the Station Record
temperature.low_c, high_c The minimum and the maximum of the air temperature at 2 m on that day.
wind.speed_mps The mean wind in daylight. The script multiplies the 3 m value by 1.26 to get the 10 m value.
wind.from_deg The vector mean of the wind direction.
clouds The preset nearest to the cloud cover that gives the measured clearness index.
rain The largest rain event of the day: its start, its end and its total.

The key _station contains more station values. The game ignores it. A replay file does not set the soil water. The folders fields_w<index> contain field setups with the measured wetness index. Set Soil and Weather shows how to use the two together.

Parameters#

environment.json#

The file is Acres/Content/Simulation/environment.json. The option -EnvConfig= selects a different file. A missing key keeps the default. When a value is out of its range, the game rejects the full file and uses the defaults.

Name Type Unit Default Description
clock.date string 2026-07-15 The start date, YYYY-MM-DD.
clock.start_hour_local number h 10 The local time at the start. Minimum 0, less than 24.
clock.utc_offset_h number h −4 Local time minus UTC.
clock.seconds_per_game_minute number s 60 Real seconds for each simulated minute. Range 0.01 to 600.
site.latitude_deg number deg 40.47 The latitude of the tile centre.
site.longitude_deg number deg −86.9925 The longitude of the tile centre, east positive.
temperature.low_c number °C 16 The minimum of the start day. Minimum −40.
temperature.high_c number °C 28 The maximum of the start day. Maximum 50.
temperature.day_to_day_sigma_c number °C 1.2 The standard deviation of the change between days.
wind.speed_mps number m/s 3.5 The mean wind at 10 m in the day. Range 0 to 40.
wind.from_deg number deg 225 The direction that the wind comes from, clockwise from north.
wind.turbulence_intensity number 0.2 The standard deviation of the speed divided by the mean.
wind.roughness_m number m 0.03 The roughness length of the surface.
clouds string fair clear, fair, partly or overcast.
rain.enabled boolean false Enables the scheduled rain event.
rain.start_hour number h 15 The start of the rain on the clock \(H_c\).
rain.end_hour number h 16 The end of the rain on the clock \(H_c\).
rain.total_mm number mm 10 The total of the event. The mean rate must be 150 mm/h or less.
rain.prior_mm number mm 0 Rain before the start, for the soil water only. Range 0 to 500.
rain.prior_hours number h 12 The duration of the rain before the start.
fog.mode string auto auto, off or fixed.
fog.visibility_m number m 800 The visibility in the mode fixed. Minimum 20.
seed integer 42 The seed of the random generator.

Command-Line Options#

The options change the values of the file. The game ignores an option that makes the settings incorrect and writes a warning.

Name Type Unit Default Description
-EnvConfig= path environment.json The environment file.
-EnvDate= string from the file The start date, YYYY-MM-DD.
-EnvHour= number h from the file The local time at the start.
-EnvMinute= number s from the file Real seconds for each simulated minute.
-EnvLowC= number °C from the file The minimum of the start day.
-EnvHighC= number °C from the file The maximum of the start day.
-EnvWind= number m/s from the file The mean wind at 10 m.
-EnvWindFrom= number deg from the file The direction that the wind comes from.
-EnvClouds= string from the file The cloud preset.
-EnvRain= 3 numbers h, h, mm no rain start,end,total. Enables the rain event.
-EnvFog= string m from the file auto, off, or a visibility in metres for the mode fixed.
-EnvSeed= integer from the file The seed.
-EnvNoRainLens flag off Removes the rain drops on the lens from all views.
-FarmRain= number mm/h Sets a constant manual rain rate.
-FarmTimeScale= number Sets the time scale \(k\) directly.
-FarmMinC=, -FarmMaxC= number °C Set the minimum and the maximum and set day_to_day_sigma_c to 0.
-FarmEvap= number mm/day Keeps the evaporation of the soil water at this value.

The game examines -EnvLowC= and -EnvHighC= together. The four -Farm options are from an older test tool. Command Line gives all options of the game.

Code Map#

Item File Function
Settings and state AcresEnvironmentModel.h AcresEnv::Settings, AcresEnv::State
Start and step AcresEnvironmentModel.cpp Model::Reset, Model::Step
Sun position AcresEnvironmentModel.cpp SolarPosition, SunriseSunset, DayOfYear
Irradiance AcresEnvironmentModel.cpp ClearSkyGhi, CloudTransmission
Temperature and humidity AcresEnvironmentModel.cpp DiurnalTemperature, RelativeHumidity, Model::EnsureDays
Rain shape AcresEnvironmentModel.cpp RainPlanFraction
Evaporation AcresEnvironmentModel.cpp PriestleyTaylorMmH
Random numbers AcresEnvironmentModel.cpp Model::Gauss, Model::OU
Settings file and options AcresEnvironment.cpp FAcresEnvironmentRuntime::LoadSettings, Initialize
Physics step AcresEnvironment.cpp FAcresEnvironmentRuntime::Advance
Sky, fog, rain particles AcresEnvironment.cpp FAcresEnvironmentRuntime::UpdateVisuals
Changes in a session AcresEnvironment.cpp SetClock, SetWeather, ToggleRain, ToggleFast
Coupling to the farm AcresVehicle.cpp AAcresVehiclePawn::AsyncPhysicsTickActor
Replay files Calibration/Weather/ground_conditions.py

Limitations#

  • The default values are estimates. Use a weather replay file for a real day.
  • The model has one rain event. A manual rate has no build-up of clouds and wind.
  • The long-wave radiation is a rule with two numbers. The gust factor is constant.
  • The wind profile has no displacement height. The roughness does not change with the crop.
  • Rain moves the air temperature to the minimum of the day immediately. The model has no thermal inertia.
  • The elevation has no refraction. The day of the year ignores leap days after the start day.
  • The night curve can make a small step at midnight when the next day has a different maximum.
  • An unknown cloud name gives the preset fair without a warning.
  • The exposure centre moves in each frame. Its speed thus changes with the frame rate.
  • The correction in step 3 of the rain rate adds rain only. The scale in step 4 removes a surplus.

References#

  • Alduchov, O. A., and Eskridge, R. E. (1996). Improved Magnus form approximation of saturation vapor pressure. Journal of Applied Meteorology, 35(4), 601-609.
  • Allen, R. G., Pereira, L. S., Raes, D., and Smith, M. (1998). Crop evapotranspiration: guidelines for computing crop water requirements. FAO Irrigation and Drainage Paper 56. Rome: FAO.
  • Box, G. E. P., and Muller, M. E. (1958). A note on the generation of random normal deviates. Annals of Mathematical Statistics, 29(2), 610-611.
  • Haurwitz, B. (1945). Insolation in relation to cloudiness and cloud density. Journal of Meteorology, 2(3), 154-166.
  • Kasten, F., and Czeplak, G. (1980). Solar and terrestrial radiation dependent on the amount and type of cloud. Solar Energy, 24(2), 177-189.
  • Koschmieder, H. (1924). Theorie der horizontalen Sichtweite. Beiträge zur Physik der freien Atmosphäre, 12, 33-53.
  • NOAA Global Monitoring Laboratory. General solar position calculations. Boulder, Colorado: NOAA.
  • Parton, W. J., and Logan, J. A. (1981). A model for diurnal variation in soil and air temperature. Agricultural Meteorology, 23, 205-216.
  • Priestley, C. H. B., and Taylor, R. J. (1972). On the assessment of surface heat flux and evaporation using large-scale parameters. Monthly Weather Review, 100(2), 81-92.
  • Steele, G. L., Lea, D., and Flood, C. H. (2014). Fast splittable pseudorandom number generators. ACM SIGPLAN Notices, 49(10), 453-472.
  • Uhlenbeck, G. E., and Ornstein, L. S. (1930). On the theory of the Brownian motion. Physical Review, 36(5), 823-841.