Rename ref_time/date -> start_date

docs/src/diagnostics/users_diagnostics.md

@@ -46,11 +46,11 @@ providing the space and output_dir defined in steps 1. and 2.
 Now that you defined your model and your writter, you can create a callback function to be called when solving your model. For example:
 
 ```Julia
-t0 = 0 # the starting time of your simulation
+t0 = 0 # the start date of your simulation
 
-reference_date = DateTime(2024) # reference_date is the DateTime of your starting time
+start_date = DateTime(2024) # start_date is the DateTime of your start date
 
-diags = ClimaLand.default_diagnostics(model, reference_date; output_writer = nc_writer)
+diags = ClimaLand.default_diagnostics(model, start_date; output_writer = nc_writer)
 
 diagnostic_handler =
     ClimaDiagnostics.DiagnosticsHandler(diags, Y, p, t0; dt = Δt)

docs/tutorials/shared_utilities/driver_tutorial.jl

@@ -24,12 +24,12 @@
 # shortwave and longwave flux (W/m^2). The radiative driver is also where
 # a function which computes the zenith angle for the site is stored.
 
-# Both drivers store the reference time for the data/simulation.
+# Both drivers store the start date for the data/simulation.
 # This is the DateTime object which corresponds to the time at which t=0
 # in the simulation. Additionally, for site-level runs, both drivers store the
 # forcing data as a spline function fit to the data which takes the time
 # `t` as an argument, where `t` is the simulation time measured in seconds since
-# the reference time. The reference time should be in UTC.
+# the start date. The start date should be in UTC.
 
 # Note: for coupled runs, corresponding types `CoupledAtmosphere`
 # and `CoupledRadiativeFluxes` exist. However, these are not defined
@@ -54,9 +54,9 @@ time_offset = 7;
 # Site latitude and longitude
 lat = 38.7441; # degree
 long = -92.2000; # degree
-# Compute the reference time in UTC, and convert local datetime
-# vector into a vector of seconds since the reference time
-ref_time = local_datetime[1] + Dates.Hour(time_offset);
+# Compute the start date in UTC, and convert local datetime
+# vector into a vector of seconds since the start date
+start_date = local_datetime[1] + Dates.Hour(time_offset);
 data_dt = 3600.0;
 seconds = 0:data_dt:((length(local_datetime) - 1) * data_dt);
 
@@ -81,16 +81,16 @@ earth_param_set = LP.LandParameters(Float64);
 insol_params = earth_param_set.insol_params # parameters of Earth's orbit required to compute the insolation
 function zenith_angle(
     t,
-    ref_time;
+    start_date;
     latitude = lat,
     longitude = long,
     insol_params = insol_params,
 )
-    current_datetime = ref_time + Dates.Second(round(t)) # Time in UTC
+    current_datetime = start_date + Dates.Second(round(t)) # Time in UTC
 
     d, δ, η_UTC = (Insolation.helper_instantaneous_zenith_angle(
         current_datetime,
-        ref_time,
+        start_date,
         insol_params,
     ))
 
@@ -110,7 +110,7 @@ radiation = ClimaLand.PrescribedRadiativeFluxes(
     Float64,
     SW_d,
     LW_d,
-    ref_time;
+    start_date;
     θs = zenith_angle,
 );
 

docs/tutorials/standalone/Bucket/bucket_tutorial.jl

@@ -156,7 +156,7 @@ using ClimaUtilities.TimeVaryingInputs: TimeVaryingInput
 # We also want to plot the solution
 using Plots
 
-# And we need to use the DateTime type to store reference times
+# And we need to use the DateTime type to store start dates
 using Dates
 
 FT = Float32;
@@ -203,7 +203,7 @@ z_0b = FT(1e-3);
 ρc_soil = FT(2e6);
 # Snow melt timescale
 τc = FT(3600);
-# Simulation start time, end time, and timestep
+# Simulation start date, end time, and timestep
 t0 = 0.0;
 tf = 7 * 86400;
 Δt = 3600.0;
@@ -214,7 +214,7 @@ bucket_parameters = BucketModelParameters(FT; albedo, z_0m, z_0b, τc);
 # The PrescribedAtmosphere and PrescribedRadiation need to take in a reference
 # time, the date of the start of the simulation. In this tutorial we will
 # consider this January 1, 2005.
-ref_time = DateTime(2005);
+start_date = DateTime(2005);
 
 # To drive the system in standalone mode,
 # the user must provide
@@ -247,7 +247,7 @@ bucket_atmos = PrescribedAtmosphere(
     TimeVaryingInput(u_atmos),
     TimeVaryingInput(q_atmos),
     TimeVaryingInput(P_atmos),
-    ref_time,
+    start_date,
     h_atmos,
     earth_param_set,
 );
@@ -262,7 +262,7 @@ bucket_rad = PrescribedRadiativeFluxes(
     FT,
     TimeVaryingInput(SW_d),
     TimeVaryingInput(LW_d),
-    ref_time,
+    start_date,
 );
 
 

docs/tutorials/standalone/Soil/evaporation.jl

@@ -39,14 +39,14 @@ thermo_params = LP.thermodynamic_parameters(earth_param_set);
 # Our assumption is that in the lab experiment there was no radiative heating
 # or cooling of the soil.
 
-ref_time = DateTime(2005) # required argument, but not used in this case
+start_date = DateTime(2005) # required argument, but not used in this case
 SW_d = (t) -> 0
 LW_d = (t) -> 301.15^4 * 5.67e-8
 radiation = PrescribedRadiativeFluxes(
     FT,
     TimeVaryingInput(SW_d),
     TimeVaryingInput(LW_d),
-    ref_time,
+    start_date,
 );
 # Set up atmospheric conditions that result in the potential evaporation
 # rate obsereved in the experiment.
@@ -74,7 +74,7 @@ atmos = PrescribedAtmosphere(
     TimeVaryingInput(u_atmos),
     TimeVaryingInput(q_atmos),
     TimeVaryingInput(P_atmos),
-    ref_time,
+    start_date,
     h_atmos,
     earth_param_set;
     gustiness = gustiness,

docs/tutorials/standalone/Soil/evaporation_gilat_loess.jl

@@ -71,14 +71,14 @@ params = ClimaLand.Soil.EnergyHydrologyParameters(
     d_ds,
 );
 
-ref_time = DateTime(2005)
+start_date = DateTime(2005)
 SW_d = (t) -> 0
 LW_d = (t) -> 294.15^4 * 5.67e-8
 radiation = PrescribedRadiativeFluxes(
     FT,
     TimeVaryingInput(SW_d),
     TimeVaryingInput(LW_d),
-    ref_time,
+    start_date,
 )
 # Atmos
 T_air = FT(301.15)
@@ -104,7 +104,7 @@ atmos = PrescribedAtmosphere(
     TimeVaryingInput(u_atmos),
     TimeVaryingInput(q_atmos),
     TimeVaryingInput(P_atmos),
-    ref_time,
+    start_date,
     h_atmos,
     earth_param_set;
     gustiness = gustiness,

docs/tutorials/standalone/Soil/sublimation.jl

@@ -25,14 +25,14 @@ FT = Float64;
 earth_param_set = LP.LandParameters(FT)
 thermo_params = LP.thermodynamic_parameters(earth_param_set);
 
-ref_time = DateTime(2005)
+start_date = DateTime(2005)
 SW_d = (t) -> 0
 LW_d = (t) -> 270.0^4 * 5.67e-8
 radiation = PrescribedRadiativeFluxes(
     FT,
     TimeVaryingInput(SW_d),
     TimeVaryingInput(LW_d),
-    ref_time,
+    start_date,
 );
 # Set up atmospheric conditions that result in the potential evaporation
 # rate obsereved in the experiment.
@@ -60,7 +60,7 @@ atmos = PrescribedAtmosphere(
     TimeVaryingInput(u_atmos),
     TimeVaryingInput(q_atmos),
     TimeVaryingInput(P_atmos),
-    ref_time,
+    start_date,
     h_atmos,
     earth_param_set;
     gustiness = gustiness,

experiments/benchmarks/bucket.jl

@@ -56,7 +56,7 @@ function setup_prob(t0, tf, Δt; nelements = (100, 10))
         npolynomial = 1,
         dz_tuple = FT.((1.0, 0.05)),
     )
-    ref_time = DateTime(2005)
+    start_date = DateTime(2005)
 
     # Initialize parameters
     σS_c = FT(0.2)
@@ -69,7 +69,7 @@ function setup_prob(t0, tf, Δt; nelements = (100, 10))
 
     surface_space = bucket_domain.space.surface
     # Construct albedo parameter object using temporal map
-    albedo = PrescribedSurfaceAlbedo{FT}(ref_time, t0, surface_space)
+    albedo = PrescribedSurfaceAlbedo{FT}(start_date, surface_space)
 
     bucket_parameters = BucketModelParameters(FT; albedo, z_0m, z_0b, τc)
 
@@ -91,7 +91,7 @@ function setup_prob(t0, tf, Δt; nelements = (100, 10))
         TimeVaryingInput(u_atmos),
         TimeVaryingInput(q_atmos),
         TimeVaryingInput(P_atmos),
-        ref_time,
+        start_date,
         h_atmos,
         earth_param_set,
     )
@@ -106,7 +106,7 @@ function setup_prob(t0, tf, Δt; nelements = (100, 10))
         FT,
         TimeVaryingInput(SW_d),
         TimeVaryingInput(LW_d),
-        ref_time,
+        start_date,
     )
 
     model = BucketModel(

experiments/benchmarks/land.jl

@@ -71,7 +71,7 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
     surface_space = domain.space.surface
     subsurface_space = domain.space.subsurface
 
-    ref_time = DateTime(2021)
+    start_date = DateTime(2021)
 
     # Forcing data
     era5_artifact_path =
@@ -80,7 +80,7 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
         joinpath(era5_artifact_path, "era5_2021_0.9x1.25_clima.nc"),
         "rf",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
         file_reader_kwargs = (; preprocess_func = (data) -> -data / 3600,),
     )
@@ -89,7 +89,7 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
         joinpath(era5_artifact_path, "era5_2021_0.9x1.25.nc"),
         "sf",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
         file_reader_kwargs = (; preprocess_func = (data) -> -data / 3600,),
     )
@@ -98,29 +98,29 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
         joinpath(era5_artifact_path, "era5_2021_0.9x1.25_clima.nc"),
         "ws",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
     )
     q_atmos = TimeVaryingInput(
         joinpath(era5_artifact_path, "era5_2021_0.9x1.25_clima.nc"),
         "q",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
     )
     P_atmos = TimeVaryingInput(
         joinpath(era5_artifact_path, "era5_2021_0.9x1.25.nc"),
         "sp",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
     )
 
     T_atmos = TimeVaryingInput(
         joinpath(era5_artifact_path, "era5_2021_0.9x1.25.nc"),
         "t2m",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
     )
     h_atmos = FT(10)
@@ -132,7 +132,7 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
         u_atmos,
         q_atmos,
         P_atmos,
-        ref_time,
+        start_date,
         h_atmos,
         earth_param_set,
     )
@@ -142,35 +142,35 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
         joinpath(era5_artifact_path, "era5_2021_0.9x1.25.nc"),
         "ssrd",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
         file_reader_kwargs = (; preprocess_func = (data) -> data / 3600,),
     )
     LW_d = TimeVaryingInput(
         joinpath(era5_artifact_path, "era5_2021_0.9x1.25.nc"),
         "strd",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
         file_reader_kwargs = (; preprocess_func = (data) -> data / 3600,),
     )
 
     function zenith_angle(
         t,
-        ref_time;
+        start_date;
         latitude = ClimaCore.Fields.coordinate_field(surface_space).lat,
         longitude = ClimaCore.Fields.coordinate_field(surface_space).long,
         insol_params::Insolation.Parameters.InsolationParameters{FT} = earth_param_set.insol_params,
     ) where {FT}
         # This should be time in UTC
-        current_datetime = ref_time + Dates.Second(round(t))
+        current_datetime = start_date + Dates.Second(round(t))
 
         # Orbital Data uses Float64, so we need to convert to our sim FT
         d, δ, η_UTC =
             FT.(
                 Insolation.helper_instantaneous_zenith_angle(
                     current_datetime,
-                    ref_time,
+                    start_date,
                     insol_params,
                 )
             )
@@ -184,7 +184,7 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
         ).:1
     end
     radiation =
-        PrescribedRadiativeFluxes(FT, SW_d, LW_d, ref_time; θs = zenith_angle)
+        PrescribedRadiativeFluxes(FT, SW_d, LW_d, start_date; θs = zenith_angle)
 
     soil_params_artifact_path =
         ClimaLand.Artifacts.soil_params_artifact_folder_path(; context)
@@ -483,7 +483,7 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
         joinpath(era5_artifact_path, "era5_lai_2021_0.9x1.25_clima.nc"),
         "lai",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
         file_reader_kwargs = (;
             preprocess_func = (data) -> data > 0.05 ? data : 0.0,

experiments/benchmarks/richards.jl

@@ -74,7 +74,7 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
     surface_space = domain.space.surface
     subsurface_space = domain.space.subsurface
 
-    ref_time = DateTime(2021)
+    start_date = DateTime(2021)
 
     # Read in f_max data and land sea mask
     infile_path = ClimaLand.Artifacts.topmodel_data_path()
@@ -195,13 +195,13 @@ function setup_prob(t0, tf, Δt; nelements = (101, 15))
     # Below, the preprocess_func argument is used to
     # 1. Convert precipitation to be negative (as it is downwards)
     # 2. Convert accumulations over an hour to a rate per second
-    ref_time = DateTime(2021)
+    start_date = DateTime(2021)
     # Precipitation:
     precip = TimeVaryingInput(
         joinpath(era5_artifact_path, "era5_2021_0.9x1.25.nc"),
         "tp",
         surface_space;
-        reference_date = ref_time,
+        reference_date = start_date,
         regridder_type,
         file_reader_kwargs = (; preprocess_func = (data) -> -data / 3600,),
     )