docs: reorganize Scientific Background documentation by energy and water balance #858
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
sunt05
temporarily deployed
to
github-pages-preview
GitHub Actions
Inactive
🔍 Schema Preview DeployedPreview URLs:
Production URLs (unchanged):
|
sunt05
temporarily deployed
to
github-pages-preview
GitHub Actions
Inactive
sunt05
temporarily deployed
to
github-pages-preview
GitHub Actions
Inactive
sunt05
temporarily deployed
to
github-pages-preview
GitHub Actions
Inactive
sunt05
temporarily deployed
to
github-pages-preview
GitHub Actions
Inactive
sunt05
temporarily deployed
to
github-pages-preview
GitHub Actions
Inactive
sunt05
temporarily deployed
to
github-pages-preview
GitHub Actions
Inactive
sunt05
temporarily deployed
to
github-pages-preview
GitHub Actions
Inactive
… tests - Add blank line before variable list for better readability - Include column header line in forcing data example - Refactor validation tests using pytest.parametrize for cleaner test organization - Consolidate repetitive test cases into parameterized tests 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Major changes: 1. Update page title - "Parameterisations and sub-models" → "Model Physics and Processes" - More accessible, aligns with other land surface model documentation - Better reflects comprehensive energy/water balance coverage 2. Replace deprecated RunControl.nml references with YAML configuration - Cloud fraction input: link to forcing data configuration - SPARTACUS config: reference ModelPhysics and spartacus sections - Surface properties: point to YAML surface configuration - LAI values: reference vegetation properties section - Snow coefficients: point to snow parameters section 3. Modernize legacy table file references - SUEWS_SiteSelect.txt → site/surface configuration in YAML - SUEWS_NonVeg.txt/SUEWS_Veg.txt → surface properties in YAML - SUEWS_Snow.txt → snow parameters section - SUEWS_SPARTACUS.nml → spartacus configuration section 4. Fix documentation build issues - Fix typo: :numfig: → :numref: (line 310) - Remove duplicate "Overview" heading in Water Balance section - Rename "Leaf area index (LAI)" to "LAI in SPARTACUS-Surface" to avoid duplicate labels All changes maintain backward compatibility by explaining where to find equivalent configuration in the YAML system. Docs build successfully with no errors. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Restructure physics documentation from single 702-line file into modular
sub-pages for improved navigation, balanced content, and correct heading levels.
Structure changes:
1. Main file (parameterisations-and-sub-models.rst, 51 lines)
- Overview of energy and water balances
- Toctree linking to physics sub-pages
- Reduced from 702 to 51 lines
2. Created physics/ subdirectory with four focused pages:
- radiation-schemes.rst (380 lines): Q* schemes
* NARP (standard)
* BEERS (point-specific, thermal comfort)
* SPARTACUS-Surface (3D canopy radiation)
- heat-fluxes.rst (65 lines): QF, ΔQS, QH, QE
* Anthropogenic heat flux (QF)
* Storage heat flux (ΔQS): OHM, AnOHM, ESTM, EHC, STEBBS
* Turbulent fluxes (QH, QE): LUMPS vs SUEWS
- water-balance.rst (145 lines): P, I, E, ΔS, R
* Evapotranspiration
* Runoff generation (infiltration + saturation excess)
* Snowmelt
- supporting-schemes.rst (155 lines): LAI, stability, RSL, CBL, CO2
* Leaf Area Index (affects both balances)
* Atmospheric stability corrections
* RSL diagnostic profiles
* Convective boundary layer
* Biogenic CO2 fluxes
* Daily state calculations
Heading level corrections:
Main file:
- Model Physics and Processes (====, level 1)
- Overview (----, level 2)
- [toctree] (maxdepth: 2)
Sub-pages (all follow same structure):
- [Topic] (====, level 1)
- [Subtopic] (----, level 2)
- [Detail] (^^^^, level 3)
- [Fine detail] ("""", level 4)
Benefits:
- **Balanced content**: Pages range from 51-380 lines (vs single 702-line file)
- **Correct hierarchy**: Proper RST heading levels throughout
- **Focused navigation**: Each physics component has dedicated page
- **Easier maintenance**: Changes isolated to relevant sub-page
- **Better sidebar**: ReadTheDocs sidebar shows clear structure
- **Cross-references**: Internal links connect related content
Documentation builds successfully with no new errors.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Restructure the "Scientific Background" documentation section following
energy balance + water balance framework as requested.
New structure (6 pages):
1. Scientific Background (overview) - NEW
2. Energy Balance - NEW (merged radiation + heat fluxes)
3. Water Balance - MOVED from physics/
4. Supporting Processes - MOVED/RENAMED from physics/
5. SUEWS Publications - RENAMED from related_publications.rst
6. References - UNCHANGED
Detailed changes:
1. Created scientific-background.rst (~60 lines)
- Overview of energy and water balance equations
- Explanation of model components
- Links to detailed pages
2. Created energy-balance.rst (~378 lines)
- Merged physics/radiation-schemes.rst + physics/heat-fluxes.rst
- Structure:
* Net All-Wave Radiation, Q* (NARP, BEERS, SPARTACUS-Surface)
* Anthropogenic Heat Flux, QF
* Storage Heat Flux, ΔQS (OHM, AnOHM, ESTM, EHC, STEBBS)
* Turbulent Heat Fluxes, QH and QE (LUMPS vs SUEWS)
3. Moved water-balance.rst from physics/ to top level (~145 lines)
- Evapotranspiration
- Runoff generation
- Snowmelt
4. Created supporting-processes.rst (~155 lines)
- Renamed from physics/supporting-schemes.rst
- Updated title to "Supporting Processes and Schemes"
- LAI, stability, RSL, CBL, CO2, daily state
5. Renamed related_publications.rst → suews-publications.rst
- Updated label: Recent_publications → suews_publications
- Updated title: "SUEWS Publications"
6. Updated index.rst toctree (lines 156-167)
- New 6-page structure in "Scientific background" section
- Updated cross-reference from parameterisations-and-sub-models to scientific_background
7. Updated cross-references throughout:
- index.rst: Recent_publications → suews_publications (2 instances)
- workflow.rst: Recent_publications → suews_publications
8. Deleted old structure:
- parameterisations-and-sub-models.rst (replaced by scientific-background.rst)
- related_publications.rst (replaced by suews-publications.rst)
- physics/ subdirectory (content moved to top level)
Benefits:
- Logical flow: Overview → Energy → Water → Supporting → Publications → References
- Clear hierarchy: Energy and water balance as two core pillars
- Easy navigation: Users find major topics immediately
- Publication visibility: SUEWS papers separated from general references
- Numbered sections: Toctree numbering makes order explicit (1-6)
Documentation builds successfully with no errors.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace 'behavior' with 'behaviour' in documentation and code comments - Replace 'color' with 'colour' in documentation (preserve API names) - Replace 'optimization' with 'optimisation' - Replace 'organize' with 'organise' - Replace 'parameterization' with 'parameterisation' - Remove 'and SuPy' from workflow.rst publications reference Technical API names (colorbar, get_color) and CSS properties preserved as per web standards. Scientific computing terms (analyze) preserved as per NumPy/SciPy conventions. Affects: 31 files (documentation, code comments, validation pipeline)
- NARP: Net All-wave Radiation Parameterisation (not parameterisation) - LUMPS: Local-scale Urban Meteorological Parameterisation Scheme Maintains title case for formal acronym definitions.
Revert commits 9b870ee and 87d42a7 as the spelling standardisation is too large for this PR and should be done separately. This reverts the following changes: - behavior → behaviour - color → colour - optimization → optimisation - organize → organise - parameterization → parameterisation - Parameterisation capitalisation in NARP/LUMPS
Replace plain text symbols with RST math notation for consistency: - Energy balance: Q*, QF, ΔQS, QH, QE → :math: notation - Water balance: P, I, E, ΔS, R → :math: notation This matches the formatting used throughout the documentation and improves rendering in HTML/PDF outputs.
- Restructure BEERS, SPARTACUS-Surface heading levels for better organisation - Reformat references section description for improved readability 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit addresses both review comments on the energy balance documentation: 1. **Math notation in headings**: Convert all energy balance component headings to use proper math notation (:math:`Q^*`, :math:`Q_F`, :math:`\Delta Q_S`, :math:`Q_H`, :math:`Q_E`) 2. **Enhanced scientific background**: Add comprehensive radiation physics section covering: - Physical basis of shortwave and longwave radiation - Urban radiation complexity (geometric, material, thermal heterogeneity) - Modelling approaches overview - Radiation data options 3. **Dedicated scheme pages**: Create separate documentation pages for each radiation scheme: - radiation-schemes/narp.rst: NARP bulk parameterisation details - radiation-schemes/beers.rst: BEERS point-specific radiation analysis - radiation-schemes/spartacus-surface.rst: SPARTACUS multi-layer radiation transfer 4. **Streamlined main page**: Update energy-balance.rst with: - Brief scheme introductions with "Best for" usage guidance - Links to dedicated pages for detailed documentation - Toctree directive for proper documentation structure Documentation builds successfully with 519 warnings (existing issues, not from these changes). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Reorganise scientific background documentation to provide textbook-quality coverage of SUEWS physical schemes. Each scheme now has a dedicated page following a consistent template structure. Changes: - Create radiation-schemes/index.rst with comprehensive overview and comparison table - Create anthropogenic-schemes/ directory with complete documentation: * index.rst - Overview and selection guidance * observed.rst - External inventory method * l11-loridan.rst - Temperature-based SAHP (Loridan et al., 2011) * j11-jarvi.rst - Degree day SAHP_2 (Järvi et al., 2011) * j19-jarvi.rst - Component-based method with CO₂ (Järvi et al., 2019) - Update energy-balance.rst to condensed overview with links to detailed schemes - Establish consistent documentation pattern across all schemes Each scheme page includes: - Physical basis with governing equations - Implementation details and assumptions - Configuration examples with YAML syntax - Applications and limitations - Proper citations and cross-references This establishes the foundation for complete scheme coverage across radiation, anthropogenic heat, storage heat, roughness, and other parameterisations. Addresses textbook-quality documentation goals for urban climate modelling.
sunt05
force-pushed
the
sunt05/docs-science-reorganize
branch
from
f40a0b8 to
75c98fa
Compare
- Replace placeholder publication references with proper citations (F08, Hogan2019Oct) - Convert numbered lists to bullet points for consistent formatting - Add introductory prose to Storage Heat Flux and Turbulent Heat Fluxes sections - Fix code-style reference to proper RST cross-reference for LUMPS comparison 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR reorganizes the Scientific Background section of the SUEWS documentation to improve logical structure and readability:
Changes
Motivation
The previous documentation structure mixed different physics components without clear organization. This reorganization groups related schemes together and provides a clearer narrative following the fundamental balance equations.
Testing