Note Formats in YAML Configuration Files#

Overview#

When generating Calculation Notes from YAML configuration files, notes can be added to document parameters. These notes are automatically extracted and added to the “Remarks” column in the generated Excel Calculation Note. This ensures Single-source-of-truth: hypothesis are directly written at the calculation time, not a posteriori.

Supported Note Formats#

Four different note formats are supported, allowing flexibility in how you document your parameters:

1. Standard Format (Preceding Line)#

The original reStructuredText-style note format with two dots:

# .. note: This parameter was selected based on thermal analysis
X_torch_input: "CH4: 94, C2H6: 4.5, N2:1"

2. Simplified Format (Preceding Line)#

A shorter format without the two dots:

# note: Selected based on worst-case scenario
P_torch: 1.2  # [bar]

3. Inline with Two Dots#

Add notes directly on the parameter line:

T_reac: 1000  # [K]  # .. note: Temperature chosen for thermal stability

4. Inline without Dots (Most Concise)#

The most concise format, useful for brief comments:

composition: "H2:50, CH4:50"  # note: Simplified composition for analysis

Edge Case: Combining Units, Comments, and Notes#

You can combine unit annotations, regular comments, and notes on the same line. The note will be extracted correctly:

T_reac: 1000  # [K] some descriptive comment. note: this is the actual note
flow_rate: 100  # [kg/s] design value. .. note: validated by CFD analysis

In these cases, only the text after note: or .. note: is captured as the note.

Real-World Examples#

Documenting Composition Adjustments#

# Original composition had CO2, but it's not available in the mechanism
X_torch_input: "CH4: 94, C2H6: 4.5, N2:1"  # note: CO2: 0.5 removed, not available in Khrabry
X_2nd_inj: "CH4: 94, C2H6: 4.5, N2:1"      # note: CO2: 0.5 removed, not available in Khrabry

Multiple Notes for Same Parameter#

Multiple notes can be added for the same parameter and will be concatenated in the Remarks column:

# .. note: Primary design consideration: thermal stability
# note: Secondary consideration: cost optimization
flow_rate: 100  # [kg/s]

Mixed Formats#

You can even mix different note formats for the same parameter:

# .. note: Chosen based on supplier specifications
# note: Validated through CFD simulations
pressure: 2.0  # [bar]  # note: Maximum operating pressure

Important Notes#

Regular Comments vs. Notes#

Regular comments (without “note:”) are not extracted and will not appear in the Calculation Note:

# This is a regular comment and will NOT appear in the Calculation Note
temperature: 300  # Regular inline comment - will NOT appear in Calculation Note

# note: This WILL appear in the Calculation Note
temperature: 300  # note: This WILL also appear in the Calculation Note

Case Insensitive#

The note keyword is case-insensitive:

# Note: This works
# NOTE: This also works
# note: This is recommended (lowercase)

However, the validation tools will warn if you use capitalized versions and recommend using lowercase for consistency.

Integration with Calculation Notes#

When you generate a Calculation Note using generate_calculation_note():

All notes from the YAML file are automatically extracted
Notes are associated with their corresponding parameters
Multiple notes for the same parameter are concatenated with newlines
Notes appear in the “Remarks” column of the Excel file
Notes are preserved across different scenarios

Best Practices#

Use consistent formatting: Choose one format and stick with it throughout your YAML files
Be concise but descriptive: Notes should provide context without being verbose
Document deviations: Always note when parameters differ from standard values or expectations
Explain composition changes: Document any species removed or adjusted in compositions
Multiple notes: Use multiple notes when there are multiple considerations for a parameter

Example: Complete YAML with Notes#

metadata:
  scenario_id: "DESIGN_V1"
  scenario_name: "Initial Design Case"
  assumptions:
    - "Feed: CO2 removed (not in mechanism)"

initial:
  # .. note: Based on supplier gas composition
  X_torch_input: "CH4: 94, C2H6: 4.5, N2:1"  # note: CO2: 0.5 removed

  # note: Standard operating pressure
  P_torch: 1.2  # [bar]

  T_reac: 1273  # [K]  # note: Selected for optimal conversion rate

  # .. note: Mass flow validated by CFD
  # note: Maximum capacity for current equipment
  m_dot_torch: 0.1  # [kg/s]