Skip to content

Set Soil and Weather#

This procedure sets the date, the weather, the rain and the soil of a session, and replays the weather of a real day. The last section shows the soil-and-weather study as an example with its measured results.

Before You Start#

  • Build the packaged game. See Run the Packaged Game.
  • Do all commands in the repository root.
  • Make sure that no other game runs. Two games can use all the memory of the GPU.
  • The commands use -RenderOffscreen. Remove this option to see the game in a window.

Each session writes its results into the folder of -VehicleOutput=. The game log is Packaged/Linux/Acres/Saved/Logs/Acres.log. Weather, Soil Water and Crops and Ground Classes give the models.

Make a Drive Script#

The sessions of this procedure do not need a driver. A drive script holds the Maxxum and stops the game.

  1. Create the file stand.json with this content.

    {"frame": "spawn", "path": [[0, 0], [100, 0]],
 "keys": [{"t": 0, "gear": 8, "speed_kmh": 0, "brake": 1, "raise": true},
          {"t": 60, "exit": true}]}

    Expected Result

    A session with -DriveScript= stops after 60 s of simulation time.

Set the Date, the Time and the Weather#

  1. Start a session with a date, a start hour and weather options.

    Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen -SessionLog \
  -DriveScript="$PWD/stand.json" -VehicleOutput="$PWD/Sessions/weather" \
  -EnvDate=2026-10-02 -EnvHour=7.5 -EnvLowC=6 -EnvHighC=17 \
  -EnvWind=5 -EnvWindFrom=300 -EnvClouds=partly -EnvFog=off -EnvSeed=7

  2. Find the start state of the weather in the game log.

    grep ACRES_ENVIRONMENT_READY Packaged/Linux/Acres/Saved/Logs/Acres.log

    Expected Result

    ACRES_ENVIRONMENT_READY day 1 07:30 | 7.3 C RH 87% | sun -3 deg | cloud 50% |
  rain 0.0 mm/h (0.0 mm) | wind 3.3 m/s from 300 | vis 8.9 km | x1
    The sun is 3° below the horizon. The wind is 3.3 m/s, because the night wind is 65 % of -EnvWind=.

  3. Read the weather columns of the session log.

    cut -d, -f3,80-84 Sessions/weather/tractor.csv | head -n 2

    Expected Result

    local_hour,air_c,rain_mmh,wind_mps,wind_from_deg,cloud_cover
7.500000,7.28,0.000,3.26,300.0,0.500
    The session log has one row for each physics step.

The table shows the same settings in the menu.

Option Menu Tab Menu Setting
-EnvDate= Additional Year, Month, Day
-EnvHour= Additional Start Time
-EnvMinute= Additional Real Seconds per Game Hour (60 times the value of the option)
-EnvLowC=, -EnvHighC= Weather Daily Low, Daily High
-EnvWind=, -EnvWindFrom= Weather Mean Wind Speed (in km/h), Wind Direction
-EnvClouds= Weather Clouds
-EnvFog= Weather Fog, Visibility
-EnvRain= Weather Rain, Start Hour, End Hour, Rain Amount
-EnvSeed= Additional Weather Seed

Note

The game ignores an option with a value that is out of range. It writes a line Ignoring -<option> into the game log.

Schedule Rain#

The option -EnvRain=start,end,total schedules one rain event. The times are hours of the start day. The total is in mm. The option -EnvMinute=1 makes the weather and the soil water 60 times faster. The vehicle physics stays at real time.

  1. Start a session on field F21 with a storm of 16.8 mm from 17:30 to 18:00.

    Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen -SessionLog \
  -DriveScript="$PWD/stand.json" -VehicleOutput="$PWD/Sessions/rain" \
  -VehicleSpawnU=480 -VehicleSpawnV=405 -VehicleSpawnYaw=-90 \
  -EnvDate=2026-06-16 -EnvHour=17.4 -EnvClouds=overcast \
  -EnvRain=17.5,18,16.8 -EnvMinute=1

    Expected Result

    The game log shows the start state with the time scale 60. 

    ACRES_ENVIRONMENT_READY day 1 17:23 | 22.4 C RH 75% | sun 42 deg | cloud 97% |
  rain 0.0 mm/h (0.0 mm) | wind 6.6 m/s from 225 | vis 12.3 km | x60

  2. Read the row of field F21 in the field report.

    grep -E "^(field|F21)" Sessions/rain/farm-fields.csv | cut -d, -f1,8-10

    Expected Result

    field,theta,pond_m,rain_m
F21,0.27158853,0.00184976,0.01690142
    The field got 16.9 mm of rain. The mean water content of its surface layer increased from 0.224 to 0.272. A mean of 1.8 mm of water stays in ponds.

  3. Read the summary of the water grid.

    cat Sessions/rain/farm-water.json

    Expected Result

    mean_rain_m is 0.0169 and mean_infiltrated_m is 0.0136. max_pond_m is 0.406 in the lowest point of the tile. 17 145 cells have more than 5 mm of water. total_residual_m is 2.9e-18.

In this session the rain rate in tractor.csv has a peak of 96 mm/h at 17:41. The integral of the rate is 16.80 mm. Below the wheels, the soil wetness goes to 1.0 in the first 10 s of the storm. The water in the ruts is 14 mm deep at 17:54.

To start a session with wet soil, set the rain before the start in the environment file: rain.prior_mm and rain.prior_hours. The menu settings are Earlier Rain and Earlier Rain Duration.

Set the Soil and the Wetness of Each Field#

A field setup changes single fields. The menu writes it from the tab Fields. You can also write the file.

  1. Create the file Fields/demo/field-setup.json.

    {
 "schema": "acres-field-setup-1",
 "fields": [
  {"field": 21, "crop": "empty", "soil": "loamy_sand", "wetness": 0.58},
  {"field": 22, "soil": "ssurgo", "wetness": 1.3},
  {"field": 25, "crop": "potato", "soil": "clay", "wetness": 1.0}
 ]
}

    The wetness 0 is the wilting point, 1 is the field capacity and 2 is saturation. The key crop changes only a field that the crop season plants.

  2. Start a session with the field setup, a global wetness and the crop stage of the date.

    Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen -SessionLog \
  -DriveScript="$PWD/stand.json" -VehicleOutput="$PWD/Sessions/fields" \
  -VehicleSpawnU=480 -VehicleSpawnV=405 -VehicleSpawnYaw=-90 \
  -FieldSetup="$PWD/Fields/demo" -FarmInitialTheta=0.3 \
  -CropSeason=2026 -CropStage=date -EnvDate=2026-07-01

  3. Find the soil and the crop lines in the game log.

    grep -E "ACRES_FIELD_SOIL|ACRES_CROP_SEASON_PLANTED" Packaged/Linux/Acres/Saved/Logs/Acres.log

    Expected Result

    ACRES_FIELD_SOIL F21 loamy_sand Ks=150.0 sealed=61.1 mm/h theta s/fc/wp=0.437/0.125/0.055
ACRES_FIELD_SOIL F25 clay Ks=4.0 sealed=0.6 mm/h theta s/fc/wp=0.475/0.396/0.272
ACRES_CROP_SEASON_PLANTED season=2026 stage=date date=2026-07-01 culled=7677
  F01:soybean:0.35 F02:soybean:0.03 ... F20:corn:0.38 F22:corn:0.13 ...
    Each planted field has its crop and its growth fraction on 1 July. Field F21 is not in the list, because its crop is empty.

  4. Read the water content of the three fields and of field F26, which has no setup.

    grep -E "^(field|F21|F22|F25|F26)" Sessions/fields/farm-fields.csv | cut -d, -f1-3,8

    Expected Result

    field,kind,growth,theta
F21,-1,0.00000000,0.09559531
F22,0,0.12889385,0.33796413
F25,2,0.45030903,0.39599531
F26,0,0.37900000,0.22858886
    F21 has no crop (kind −1) and the water content of loamy sand at the index 0.58. F25 has potato (kind 2) on clay at its field capacity of 0.396. F26 uses the global value 0.3.

The table shows the options for the soil and the crops.

Option Effect
-FieldSetup=<folder> Crop, soil and start wetness of single fields, and terrain edits.
-FarmInitialTheta= Start wetness of all other soil, from 0 (wilting point) to 1 (field capacity).
-FarmKsatScale= A factor on the conductivity of all soil.
-FarmPreDays= Days that the soil water runs before the session starts.
-CropSeason= 2026 for the crop map of 2026, or legacy.
-CropStage=date Growth of each field from its planting date to the date of -EnvDate=.
-FarmInitialGrowth= The same growth fraction for all planted fields.

In the menu, the tab Fields has one row for each field with the columns Crop, Soil, Start Wetness and Terrain. The menu limits the start wetness to 1.3. The crop season and the crop stage are on the tab Additional.

Replay the Weather of a Real Day#

The folder Calibration/Weather/Replay contains one environment file for each day with real Polaris runs. The folders fields_w<index> contain field setups that give all fields the measured wetness index of a day. Calibration/Weather/ground_conditions.md gives the index of each day.

  1. Start a session with the weather of 18 June 2026 and a wetness index of 1.65.

    Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen -SessionLog \
  -DriveScript="$PWD/stand.json" -VehicleOutput="$PWD/Sessions/replay" \
  -VehicleSpawnU=480 -VehicleSpawnV=405 -VehicleSpawnYaw=-90 \
  -EnvConfig="$PWD/Calibration/Weather/Replay/env_2026-06-18.json" -EnvHour=17.8 \
  -FieldSetup="$PWD/Calibration/Weather/Replay/fields_w1.65"

    Expected Result

    The game log shows the weather of the station at 17:48. 

    ACRES_ENVIRONMENT_READY day 1 17:48 | 21.5 C RH 68% | sun 38 deg | cloud 59% |
  rain 0.0 mm/h (0.0 mm) | wind 5.9 m/s from 304 | vis 14.1 km | x1
    The low and the high of the day are 16.1 °C and 22.7 °C. They are in farm-weather.csv.

  2. Read the water content of the fields.

    grep -E "^(field|F21|F30)" Sessions/replay/farm-fields.csv | cut -d, -f1,8

    Expected Result

    field,theta
F21,0.37539529
F30,0.40007296
    The water content of F21 is 65 % of the range from its field capacity (0.297) to saturation (0.418).

Note

A replay file sets the weather only. The station record does not contain the soil of each field. Use the field setup of the day, or -FarmInitialTheta= for an index of 1 or less.

Change the Conditions in a Running Session#

The service acres/set_conditions changes the clock, the weather and the soil water while the session runs. The game needs the simulator control channel, and ROS 2 needs the ROS 2 bridge.

CAUTION

The soil wetness of this service has a different scale: 0 is the wilting point and 1 is saturation. A field setup uses 1 for the field capacity and 2 for saturation.

  1. Copy stand.json to stand-long.json. Change the time of the key exit from 60 to 300.

  2. Start the game with the simulator control channel, the sensor stream and the vehicle bridge.

    Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen -SessionLog \
  -DriveScript="$PWD/stand-long.json" -VehicleOutput="$PWD/Sessions/conditions" \
  -VehicleSpawnU=480 -VehicleSpawnV=405 -VehicleSpawnYaw=-90 \
  -SimControl=5600 -SensorStream=5601 -RlPort=5556

  3. In a second terminal, start the ROS 2 bridge.

    source ROS/Env/setup_env.sh
ros2 launch acres_sim sim_bridge.launch.py vehicle:=maxxum namespace:=maxxum

    Expected Result

    The bridge writes simulator control: connected to 127.0.0.1:5600. The command ros2 service list shows /acres/set_conditions.

  4. In a third terminal, set the surface layer of field F21 to 90 % of the range to saturation.

    source ROS/Env/setup_env.sh
ros2 service call /acres/set_conditions acres_interfaces/srv/SetConditions \
  "{set_soil_water: true, soil_wetness: 0.9, soil_fields: [21]}"

    Expected Result

    response:
acres_interfaces.srv.SetConditions_Response(result=simulation_interfaces.msg.Result(
  result=1, error_message=''), message='soil wetness 0.90 on 432 cells')

  5. Read the state of field F21.

    ros2 service call /acres/farm_state acres_interfaces/srv/FarmState "{fields: [21]}"

    Expected Result

    The response contains theta_mean=0.39096829070977535 for F21. The value before step 4 was 0.224.

  6. Start a storm.

    ros2 service call /acres/set_conditions acres_interfaces/srv/SetConditions \
  "{set_weather: true, weather: 'storm', rain_mm_h: -1.0}"

    Expected Result

    The message of the response is weather storm rain -1.0 mm/h. The negative rate selects the rate of the preset. The session log shows rain_mmh 30.000 and cloud_cover 0.970 from that time.

  7. Set the clock to a new date and hour.

    ros2 service call /acres/set_conditions acres_interfaces/srv/SetConditions \
  "{set_clock: true, date: '2026-10-02', local_hour: 8.5}"

    Expected Result

    The message of the response is clock 2026-10-02 8.50 h. The column local_hour of the session log continues from 8.50. The storm continues, because the clock change keeps the other settings.

Stop the ROS 2 bridge with Ctrl+C when the session ends. The same requests are available as JSON on the simulator control channel. See Simulator Control Channel.

The keys J and K change the weather from the keyboard. J starts or stops rain of 20 mm/h. K makes the clock 600 times faster.

Worked Example: The Soil-and-Weather Study#

The study drives the Maxxum with the chisel plow on field F21 under different soil states and through a real storm. All sessions use the same drive script. The results are in Calibration/Tractor/soil_weather_results.md.

Item Value
Vehicle Maxxum, gear 8, speed set to 8 km/h.
Implement Chisel plow with 9 shanks, draft control at 22 kN, depth limit 25 cm.
Field F21, Toronto-Millbrook silt loam, crop removed by the field setup.
Drive script Demo/SoilWeather/pass.json: a straight pass of 90 m. The steady window is 12 s to 41 s.
Soil state The measured wetness index of the day, from Demo/SoilWeather/Fields/<state>/field-setup.json.
Weather The weather replay file of the day.

CAUTION

The analysis of step 2 writes soil_weather_results.json and the figures into Calibration/Tractor. It replaces the committed files.

  1. Run the sessions. The variable SESSIONS selects some of the 12 sessions.

    SESSIONS="dry wet rain" Demo/soil_weather.sh Sessions/study

    Expected Result

    Each session writes its session folder Sessions/study/<session> and its game log Sessions/study/<session>-game.log. The file tractor.csv has 5401 rows for dry and 12 002 rows for rain. The field report of rain shows 16.81 mm of rain and a tilled area of 439 m² on F21.

  2. Compute the tables and the figures.

    python Calibration/Tractor/soil_weather_analysis.py Sessions/study

    Expected Result

    The script prints the tables in Markdown. These are three lines of the first table. 

    | Scenario | Soil state | Speed, km/h | Slip front / rear, % | ... | Fuel, L/ha | Tractive eff. |
| Dry silt loam | silt loam, θ 0.236, Se 0.47, CI 2.14 MPa, wet 0.00 | 7.83 | 4.4 / 2.9 | ... | 9.1 | 0.79 |
| Wet silt loam | silt loam, θ 0.374, Se 0.87, CI 0.63 MPa, wet 0.02 | 7.81 | 4.8 / 3.4 | ... | 9.4 | 0.78 |

The script starts each session with these soil and weather options.

Session Soil Options Weather Options
dry -FarmInitialTheta=0.58, field setup dry (index 0.58) env_2026-07-30.json, -EnvHour=15.4
wet -FarmInitialTheta=1.0, field setup wet (index 1.64) env_2026-06-18.json, -EnvHour=17.8
saturated -FarmInitialTheta=1.0, field setup saturated (index 2.0) env_2026-06-18.json, -EnvHour=17.8
loamy-sand, sand -FarmInitialTheta=0.58, field setup with the preset env_2026-07-30.json, -EnvHour=15.4
rain -FarmInitialTheta=1.0, field setup rain (index 1.12) env_2026-06-16.json, -EnvHour=17.133, -EnvMinute=1

Measured Results#

The table shows the steady state of the chisel pass from the committed results.

Session Water Content Cone Index Rear Slip Rear Rut Draft Depth Fuel
Dry silt loam 0.236 2.14 MPa 2.9 % 1.2 cm 21.1 kN 18.8 cm 9.1 L/ha
Wet silt loam 0.374 0.63 MPa 3.4 % 1.9 cm 21.7 kN 19.2 cm 9.4 L/ha
Saturated silt loam 0.417 0.48 MPa 4.5 % 3.5 cm 22.6 kN 22.1 cm 9.9 L/ha
Dry loamy sand 0.096 0.95 MPa 3.6 % 1.6 cm 20.7 kN 25.6 cm 9.0 L/ha
Dry sand 0.067 0.79 MPa 3.6 % 1.2 cm 20.3 kN 25.9 cm 8.8 L/ha
  • Wet silt loam has less strength. The slip, the rut depth and the fuel for each hectare increase from dry to saturated.
  • The draft control holds the draft. The tines go deeper when the soil is weaker.
  • Sand has no cohesion. The tines reach the depth limit and the draft stays below the set-point.

In the session rain, the storm of 16.8 mm arrives 22 s after the start.

Time Water Content Cone Index Surface Wetness Water at the Rear Tyres Rear Slip Rear Rut
Before the storm, 10 s to 21 s 0.311 1.05 MPa 0.01 0 mm 3.2 % 1.6 cm
In the storm, 27 s to 37 s 0.325 0.93 MPa 1.00 16.2 mm 3.5 % 1.6 cm
Second pass, 68 s to 95 s 0.345 0.79 MPa 0.98 11.5 mm 3.6 % 1.7 cm

The surface becomes wet in one second, and the slip increases immediately. The water content of the 0.3 m layer increases in minutes. The draft and the depth do not change, because the draft control holds the draft.

The sessions dry, wet and rain ran again for this page, on 2 October 2026. The steady-state values were the same as the committed results. The largest differences were 1 N of soil resistance and 0.1 mm of water.

Next Steps#