# Virtual Joint Field Campaign

## Summary

The Virtual Joint Field Campaign (vJFC) conducts soil-moisture-related measurements in a virtual environment. The vJFC bundles the efforts of generating multiple versions of this virtual environment and conducting the respective "virtual observations" therein. These comprise neutron flux, hydrogravimetry and radiation.
Based on these "virtual observations", the performance of different reconstruction methods (i.e. estimates of the "virtual truth") can be generated and compared. 
The resulting findings will reveal new insights in methods for their generalisation to real-world settings. 

## Reference
Francke et al.: "Virtual joint field campaign: a framework of synthetic landscapes to assess multiscale measurement methods of water storage", 
10.5194/gmd-2024-106

## Terminology
compartment:	set of environmental features that is required as a spatial input to any of the models, e.g. "groundwater", "atmosphere", "relief", ... A compartment may comprise multiple basic interrelated attributes (e.g. "vegetation" with the attributes "LAI", "height", ...). Different manifestations of a compartment are called "scenarios" (sheet 'compartment_scenarios' in central table)
layer:	vertical spatial discretization unit (e.g. used in URANOS), can result from multiple compartments (e.g. "air" and "vegetation")
model:	model that will simulate the virtual environments to generate the virtual observations, i.e. URANOS (neutron flux), RTM (radiation) and gravimetric field (gravimetry)
scenario:	Concrete manifestation of a compartment (sheet 'compartment_scenarios'  in central table), e.g. "dry homogenous soil"
scenario ranges:	sytematically varied sequence of scenarios of a compartment, e.g. soil moisture values 5-50 %
realization:	combination of different scenarios of compartments to a specific virtual truth, to be used to generate the concrete input to the models	
reconstruction:	variable of interest (e.g. soil moisture) reconstructed from virtual observations
virtual observation:	model results from a specific realization (sheet 'realizations_detailed' in central table).
attributes:	basic (physical) parameters associated to scenarios of layers

(taken from [Terminology](https://docs.google.com/spreadsheets/d/1geY2I6BGHB1wngd3d-zGLI64Xt-WzDXxiDaL_4yIP1Y/edit#gid=0) )

## Model domain properties (extent, resolution, location)

The properties are defined in sheet 'scale_requirement' in the [central table](https://docs.google.com/spreadsheets/d/154HsU45xsHGDIIAYWvIKypemmgoweu-mo5pbbcr1ztY/edit#gid=1920447957). (1000 m x 1000 m in 1 m resolution). Horizontal resolution: 1 m `nx` = 1000 (number of columns) `ny` = 1000 (number of rows) `nz` = various (number of vertical layers)

The coordinates are given in positive values towards right (east) and up (north), as in a conventional mathematical coordinate system:

```

   ^
y  |
   L----->
      x
```

z-axis points upward (positively increasing upward, i.e. inverted compared to URANOS).

The location of the lower left corner  (southwest) may be specified via the variables 'x_sw' and 'y_sw' (see below), with the respective projection given as the Proj4-string .

## Model output / Virtual observations

### Neutron simulation

* Neutron (epithermal and thermal) flux at
  * standard detector height above surface for all core area pixels
  * airborne detector altitude (30 m + other altitudes)
  * ...

### Radiative transfer model

* spectra 
* indices as proxies for soil moisture, biomass estimate, etc.

### Hydrogravimetric model

* gravimetric field
* difference in gravimetric field

## Folder structure

```
0_compartments e.g. "relief", "vegetation", etc.
	[compartment]			e.g. "snow"
		[scenario]
			[compartment_layer]_2D.nc* (if applicable: 2D matrix containing scalar value, e.g. height of material)
			[compartment_layer]_3D.nc**	  (3D matrix of properties of each voxel regarding allowed variables, e.g. "material_id", "dens")
			raw/
				[any original files (data and scripts) the scenario is based on]

1_realizations
	[realization_id]			e.g. "+SM"
		fulldomain_3D.nc	(3D matrix of URANOS-id of each voxel in variable "material_id")

3_neutron_simulations
	[realization_id]
		[*.*] (compiled URANOS input files)
		[*.*] (raw model output)
		post_processed
				[model output converted to common exchange format]

3_rtm_simulations
	[realization_id]
		{analogue to "3_neutron_simulations"}

3_gravimetric_simulations
	[realization_id]
		{analogue to "3_neutron_simulations"}
xmisc_scripts	Python scripts for interactive inspection and generation of figures
```

# Specifications for netCDF-files

## Dimensions (refer to pixel/voxel centres and voxel tops:

* `x`: 1:nx
* `y`: 1:ny
* `z`: 1:nz
* `x_sw`, `y_sw`: (optional) coordinates of lower left corner of domain

## Variables

* 2D: (file with suffix "\*\_2D.nc")
  * [variable]: (nx x ny [m])
* 3D: (file with suffix "\*\_2D.nc")
  * [variable] (nx x ny x nz )
* `zmin`: lower boundary of lowermost layer [m]
* `Proj4`: (optional) projection string (e.g. "+proj=utm +zone=34 +datum=WGS84 +units=m +no_defs") 

  "swe", "sm" , ... -> see vocabulary of SUPRATOOL catalogue
  
## Attributes
  
  for each variable, an equally named attribute holding the respective units may be given

## Variable names and units (following SUPRA-Tool conventions)
Column "required by" encodes, for which models the attributes are mandatory. 
"U": URANOS, "G": gravimetric model; "R": radiative transfer model.

```
| Variable name | description             | unit         | required by |
|---------------|-------------------------|--------------|-------------|
| sm            | soil moisture           | Vol-%        | U G         |
| bulk_density  | UR bulk density         | g cm-3       | U G         |
| swe           |  snow water             | equivalent mm m-2 (sic!)   |
| sh            | snow height             | mm           |             |
| sm            | soil moisture           | Vol-%        |             |
| material_id   | material ID according to URANOS|   -   |             |
| dens          | true/effective density  |  g cm-3      |             |
| porosity      | porosity                |  [-]         |             |
```