GEMB input variable names and default values

[chadagreene]

In reference to Issue #19, I'd like to consider renaming the variables that input to the GEMB function and setting their default values as described below. What are your thoughts on these potential changes?

Current Name	Recommended Name	Rec. Default Value	Units	Description
dateN	time		datenum	Time array corresponding to input precipitation, air_temperature, etc.
P0	precipitation		kg m^-2	Precipitation time series.
Ta0	air_temperature		K	Near-surface (2 m) air temperature time series.
V0	wind_speed		m s^-1	Near-surface (10 m) wind speed time series.
dsw0	downward_shortwave_radiation		W m^-3	Downward shortwave radiation flux time series.
dlw0	downward_longwave_radiation		W m^-2	Downward longwave radiation flux time series.
eAir0	vapor_pressure		Pa	Screen-level vapor pressure time series. (Is this a req'd input, or can it be calculated by GEMB?)
pAir0	air_pressure		Pa	Screen-level air pressure time series.
isrestart	initial_state	[delete]	structure	Restart flag can be handled by delcaring initial_state = restart_structure.
S.Adiffini	diffuse_albedo	diffuse_albedo = albedo_sza50 when albedo_method = "gardner_2009", diffuse_albedo = snow_albedo otherwise.	fraction	Surface albedo for diffuse radiation
S.adThresh	albedo_density_threshold	Inf	kg m^-3	Density threshold below which albedo_method is applied.
S.aIce	ice_albedo	0.48	fraction	Ice albedo.
S.aIdx	albedo_method	"gardner_2009"	n/a	Method of calculating albedo and subsurface absorption.
S.Aini	[delete]	[delete]	fraction	Albedo on restart (delete bc snow_albedo value will be overridden by values in restart_structure)
S.aSnow	snow_albedo	0.85	fraction	New snow albedo.
S.aValue	[not necessary]	[delete]	fraction	Recommend setting albedo to snow_albedo value when albedo_method = "constant".
S.C	snow_accumulation_mean	?	kg m^-2 yr^-1	Mean annual snow accumulation.
S.cciceValue	carbon_concentration_ice	0	ppmw	Concentration of light-absorbing carbon for ice.
S.ccsnowValue	carbon_concentration_snow	0	ppmw	Concentration of light-absorbing carbon for snow.
S.cldFrac	cloud_fraction	0.1	fraction	Cloud amount described as n in Greuell & Konzelmann, 1994 https://doi.org/10.1016/0921-8181(94)90010-8
S.cotValue	cloud_optical_thickness	?	unitless?	Cloud optical thickness.
S.denIdx	densification_method	"arthern_2010"	n/a	Method of calculating densification of snow/firn.
S.Dini	[delete]	[delete]	kg m^-3	Density (delete bc ice_density will be overridden by values in restart_structure)
S.dsnowIdx	snow_density_method	"constant"	n/a	Definition of fresh snow density.
S.dswdiffrf	downward_shortwave_radiation_diffuse	0	W m^-2	Downward diffusive shortwave radiation flux
S.dulwrfValue	?	0	W m^-3	Needs a more descriptive variable name. This variable gets renamed deltaULW in thermo.m.
S.Dzini	?	?	m	The code implies Dzini defines dz, but the S2A1D_000001.mat file contains only values of 0.05 for Dzini, which corresponds to z_top.
S.dzMin	dz_min	dz_top/2	m	Minimum allowable grid spacing.
S.dzTop	dz_top	0.05	m	Spacing of the upper portion of the model grid.
S.ECini	evaporation_condensation	0	kg m^-2	Surface evaporation (negative) or condensation (positive).
S.eIdx	emissivity_method	"constant"	n/a	Method of calculating emissivity.
S.Gdnini	grain_dendricity	1	unitless	Grain dendricity
S.Gspini	grain_sphericity	0.5	unitless	Grain sphericity
S.isdeltaLWup	[delete]	false	boolean	Not necessary as an input, because it can be determined by the value of
S.K	constant_K	days/K	7	Timescale constant from Table 2 of Bougamont et al., 2005 https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2005JF000348.
S.outputDir	[not necessary]	[delete]	n/a	Will be included in output_filename
S.outputFreq	output_frequency	"monthly"	n/a
S.Reini	grain_radius	2.5	mm	Effective radius of snow grains.
S.runID	output_filename	none	n/a	Name of output file. Must have either .h5 or .mat extension (e.g., "myfile.h5" or "myfile.mat")
S.Sizeini	?	?	?	Needs a more descriptive variable name.
S.spinUp	spinup_cycles	0	n/a	Number of cycles of met data run before output.
S.swIdx	shortwave_penetration	true	boolean	If true, shortwave penetration is calculated based on albedo_method. Otherwise, all shortwave radiation is absorbed by the top grid cell.
S.szaValue	solar_zenith	0	degree	Solar zenith angle.
S.t0dry	albedo_timescale_dry	30	days	Timescale for dry snow albedo decay from Table 2 of Bougamont et al., 2005
S.t0wet	albedo_timescale_wet	15	days	Timescale for wet snow albedo decay from Table 2 of Bougamont et al., 2005
S.tcIdx	conductivity_method	"sturm_1997"	n/a	Method of calculating thermal conductivity.
S.teThresh	emissivity_radius_threshold	10	mm	Grain radius threshold above which emissivity_method is applied.
S.teValue	emissivity	0.97	unitless	Outward longwave radiation thermal emissivity forcing at every element.
S.ThermoDeltaTScaling	thermo_scaling_factor	1/11	unitless	Scaling factor to multiply the thermal diffusion timestep (delta t).
S.Tini	snow_temperature	mean(air_temperature)	K	Snow temperature
S.Tmean	air_temperature_mean	mean(air_temperature)	K	Mean annual surface temperature.
S.Vmean	wind_speed_mean	0	m s^-1	Mean annual wind speed.
S.Wini	water_content	zeros(size(time))	kg m^-2	Water content
S.zMax	z_max	250	m	Maximum thickness of the total column.
S.zMin	z_min	ceil(z_max/2 /10)*10	m	Minimum model depth.
S.zTop	z_top	10	m	Thickness of the upper portion of the model grid, in which grid spacing is constant.
S.zY	beta	1.025	unitless	Grid cell stretching parameter for the lower portion of the model grid, in which grid length increases linearly with depth.
[not a current option]	ice_density	910	kg m^-3	Density of ice.
[not a current option]	add_cells	1000	integer	Currently defined within GEMB as S.addCells: number of addtional vertical levels.
[not a current option]	snow_density	350	kg m^-3	Density of snow used if snow_density_method = "constant".
[not a current option]	print_status	true	boolean	Print the current status of the calculation to the command window.

[alex-s-gardner]

I believe S.aValue is needed when user supplies an a priori albedo for when S.adThresh is exceeded. @NJSchlegel added this and can confirm

S.cciceValue should be 'black_carbon_concentration_iceorlight_absorbing_carbon_concentration_ice S.ccsnowValueshould be 'black_carbon_concentration_snow or light_absorbing_carbon_concentration_snow

Variables with ? are owned by @NJSchlegel

[NJSchlegel]

dulwrfValue is if the user wants to run sensitivity tests to perturb LW up. I am doing this myself, so it made sense to add an option for it instead of keep hacking inside the code. It didn't make sense for me to remove that functionality once it was built in. Don't we need Dzini to define the mx1 depth of the layers of all the ini variables? Sizeini is the "m" of all the ini variables, which in matlab can just be calculated, but for c++ it is helpful to pass in. Maybe mini is more meaningful? cotValue should be 0.0 I believe, as set it MASTER_RUN.m . S.C is a mean of the accumulation, so does not technically have a default. It should be an input (like S.Tmean and S.Vmean). Also, I think Vmean needs to have a value > 0. In ISSM, the input uses 10 m/s. Also agree with @alex-s-gardner, aValue will need to be set for the case when adThresh is exceeded (not just when the albedo option is constant).