—

Generate a Calculation Note using a YAML configuration.

This minimal example demonstrates the high-level API for generating calculation notes from YAML configuration files. It uses the generate_calculation_note() function which:

1. Reads a YAML file with an export section

2. Runs the base scenario and any overlay scenarios

3. Collects results and metadata

4. Generates an Excel Calculation Note automatically

This is similar to how models/SPRING_A3/run_scenarios.py works.

Note: Calculation note generation requires openpyxl and may fail in CI environments without display capabilities or Excel dependencies.

from pathlib import Path

from bloc.batch import import_simulation
from bloc.calc_note import generate_calculation_note
from bloc.utils import get_file_path

Step 1: Prepare YAML configuration with export section

We’ll use the default_simulation.yaml and add an export section. The export section configures the calculation note report.

# Read the default simulation YAML
default_yaml = get_file_path("default_simulation.yaml")

# Add export section to configure the calculation note
yaml_addition = """

# Metadata for document header
metadata:
  scenario_id: "BASE"
  scenario_name: "Default Simulation Example"
  architecture: "Single reactor with heating"
  pid_no: "EX-001"
  tag_name: "R-101"
  doc_no: "CN-EXAMPLE-001"
  rev: "A"
  project: "Calculation Note Example"
  designed_by: "Bloc User"
  client: "Example Client"
  assumptions:
    - text: "Ideal gas behavior"
    - text: "Steady state operation"

# Export configuration for calculation note
export:
  calc_note: "Example_Calculation_Note.xlsx"
  title: "Example Calculation Note"
  subtitle: "Generated from default_simulation.yaml"
  main_species: 8       # Top species by mole fraction (gas-phase only)
  main_species_mass: 6  # Top species by mass fraction (gas-phase only)
  minimum_mole_fraction_balance: 0.95  # Add species until cumulative mole >= 95%; 0 to disable
  minimum_mass_fraction_balance: 0.95  # Add species until cumulative mass >= 95%; 0 to disable
  mandatory_species:    # Species that must always appear
    - H2
    - CH4
"""

Step 2: Create YAML and generate calculation note

# Create output directory in examples folder
output_dir = Path(__file__).parent / "output"
output_dir.mkdir(exist_ok=True)

# Create YAML with export section
yaml_file = output_dir / "config_with_export.yaml"
yaml_content = Path(default_yaml).read_text() + yaml_addition
yaml_file.write_text(yaml_content)

# Import the simulation module
# For your own simulations, use: import_simulation("path/to/your_simulation.py")
module = import_simulation(str(Path(__file__).parent.parent / "bloc" / "test.py"))

print("=" * 80)
print("Generating Calculation Note from YAML...")
print("=" * 80)

# Generate the calculation note with error handling for CI environments
try:
    # This single function call does everything:
    # - Reads the YAML configuration
    # - Runs the simulation
    # - Collects inputs, outputs, and metadata
    # - Generates the Excel file with all sections and TOTAL rows
    excel_path = generate_calculation_note(
        base_yaml=yaml_file,
        module=module,
        output_dir="Results",
    )

    if excel_path:
        print(f"\n{'=' * 80}")
        print("Success! Calculation Note generated.")
        print(f"{'=' * 80}")
        print(f"File: {excel_path.name}")
        print(f"Location: {excel_path.parent}")
        print("\nThe Excel file includes:")
        print("  ✓ Input parameters from YAML")
        print("  ✓ Output results from simulation")
        print("  ✓ Mole fractions with TOTAL row (light grey formula)")
        print("  ✓ Mass fractions with TOTAL row (light grey formula)")
        print("  ✓ Metadata and assumptions")
        print("  ✓ Automatic formatting with Spark colors")
    else:
        print("No calculation note generated (no export section found)")

except Exception as e:
    print(f"\n{'=' * 80}")
    print("Calculation Note generation failed")
    print(f"{'=' * 80}")
    print(f"Error: {e}")
    print("\nThis may occur in CI environments without:")
    print("  - openpyxl package")
    print("  - Display capabilities")
    print("  - Excel dependencies")
    print("\nThe simulation still ran successfully; only Excel export failed.")

That’s it! Just 3 steps:

print(f"\n{'=' * 80}")
print("Summary - 3 steps to generate a calculation note:")
print(f"{'=' * 80}")
print("1. Add an 'export' section to your YAML configuration")
print("2. Import your simulation module")
print("3. Call generate_calculation_note(yaml_file, module)")
print("\nSee models/SPRING_A3/run_scenarios.py for a production example.")