Fix #290: Add documentation for SMD method and FcPhoto issues

docs/source/inputs/tables/RunControl/csv-table/SMDMethod.csv

@@ -1,14 +1,30 @@
 "Value","Comments"
 0,"
-SMD modelled using parameters specified in `SUEWS_Soil.txt`.
-|Recmd|"
+SMD modelled using water balance and parameters specified in `SUEWS_Soil.txt`.
+The model calculates soil moisture deficit based on precipitation, evapotranspiration, and runoff.
+|Recmd| for sites without soil moisture observations.
+
+**Important considerations:**
+- Requires proper initialization of soil moisture states (soilstore_id values)
+- Initial values that are too low can lead to severe water stress
+- May cause FcPhoto to approach zero in summer if not properly configured
+- Consider enabling irrigation (WaterUseMethod) for urban areas
+- See troubleshooting guide if FcPhoto values are unexpectedly low
+"
 1,"
 Observed SM provided in the meteorological forcing file is used.
-Data are provided as volumetric soil moisture content.
+Data are provided as volumetric soil moisture content (m³ water/m³ soil).
 Metadata must be provided in `SUEWS_Soil.txt`.
+
+**Advantages:**
+- Bypasses internal soil water balance calculations
+- More reliable for sites with good soil moisture measurements
+- Recommended solution if FcPhoto issues occur with method 0
 "
 2,"
 Observed SM provided in the meteorological forcing file is used.
-Data are provided as gravimetric soil moisture content.
+Data are provided as gravimetric soil moisture content (kg water/kg dry soil).
 Metadata must be provided in `SUEWS_Soil.txt`.
+
+**Note:** The model will convert gravimetric to volumetric content using soil bulk density.
 "

docs/source/troubleshooting.rst

@@ -241,3 +241,84 @@ Common validation errors:
 - Missing vegetation parameters when vegetation surfaces are present
 
 
+FcPhoto (Photosynthesis Flux) Near Zero in Summer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Problem**: FcPhoto values become close to 0 during summer months (May-September) when they should be at their highest.
+
+**Cause**: This typically occurs when using SMD (Soil Moisture Deficit) method 0 with improper soil moisture initialization or parameters, leading to severe water stress that shuts down photosynthesis.
+
+**Background**: The photosynthesis flux (FcPhoto) is regulated by several environmental stress factors:
+
+- **g_dq**: Vapour pressure deficit stress
+- **g_ta**: Temperature stress  
+- **g_smd**: Soil moisture stress
+- **g_kdown**: Light stress
+
+These are combined into a total stress factor: ``gfunc = g_dq × g_ta × g_smd × g_kdown``
+
+When using SMD method 0 (modelled soil moisture), the soil water balance is calculated internally. If the soil moisture becomes too low, ``g_smd`` approaches 0, causing ``FcPhoto`` to approach 0.
+
+**Solutions**:
+
+1. **Switch to SMD method 1 or 2** (recommended if you have observed soil moisture data):
+
+   In your YAML configuration::
+
+       smd_method: {value: 1}  # Use observed volumetric soil moisture
+       # or
+       smd_method: {value: 2}  # Use observed gravimetric soil moisture
+
+   This requires providing soil moisture data in your forcing file.
+
+2. **If using SMD method 0**, check and adjust:
+
+   a. **Initial soil moisture states** - ensure reasonable starting values::
+
+       initial_conditions:
+         soilstore_bldgs: {value: 50.0}  # Not too low
+         soilstore_paved: {value: 50.0}
+         soilstore_evetr: {value: 100.0}
+         soilstore_dectr: {value: 100.0}
+         soilstore_grass: {value: 80.0}
+         soilstore_bsoil: {value: 60.0}
+
+   b. **Soil capacity parameters** - verify they match your site::
+
+       soil:
+         bldgs:
+           soilstorecap: {value: 150.0}  # mm
+         paved:
+           soilstorecap: {value: 150.0}
+         # ... similar for other surfaces
+
+   c. **Soil moisture stress parameters**::
+
+       vegetation:
+         s1: {value: 5.56}   # Wilting point threshold (mm)
+         s2: {value: 100.0}  # Capacity threshold (mm)
+         g_sm: {value: 3.5}  # Soil moisture sensitivity
+
+   d. **Enable irrigation** if appropriate for your site::
+
+       water_use:
+         method: {value: 1}  # Enable irrigation
+         # Configure irrigation parameters
+
+**Diagnostic Steps**:
+
+1. Check the daily state output for soil moisture values
+2. Plot SMD alongside precipitation and FcPhoto
+3. Look for correlation between rain events and FcPhoto spikes
+4. Verify that LAI values are reasonable for the vegetation present
+
+**Example**: If FcPhoto only appears briefly after rain events, this confirms severe water stress is limiting photosynthesis between precipitation.
+
+**Prevention**: When setting up a new simulation:
+
+- Use realistic initial soil moisture (not 0 or very low values)
+- Consider seasonal variation in soil parameters
+- If modelling urban areas, account for irrigation
+- Validate soil parameters against local measurements if available
+
+