Atomizer/docs/protocols/operations/OP_08_GENERATE_REPORT.md

OP_08: Generate Study Report

Overview

This protocol covers automated generation of comprehensive study reports via the Dashboard API or CLI. Reports include executive summaries, optimization metrics, best solutions, and engineering recommendations.

---

When to Use

Trigger	Action
"generate report"	Follow this protocol
Dashboard "Report" button	API endpoint called
Optimization complete	Auto-generate option
CLI atomizer report <study>	Direct generation

---

Quick Reference

API Endpoint: POST /api/optimization/studies/{study_id}/report/generate

Output: STUDY_REPORT.md in study root directory

Formats Supported: Markdown (default), JSON (data export)

---

Generation Methods

1. Via Dashboard

Click the "Generate Report" button in the study control panel. The report will be generated and displayed in the Reports tab.

2. Via API

# Generate report
curl -X POST http://localhost:8003/api/optimization/studies/my_study/report/generate

# Response
{
  "success": true,
  "content": "# Study Report: ...",
  "path": "/path/to/STUDY_REPORT.md",
  "generated_at": "2026-01-06T12:00:00"
}

3. Via CLI

# Using Claude Code
"Generate a report for the bracket_optimization study"

# Direct Python
python -m optimization_engine.reporting.markdown_report studies/bracket_optimization

---

Report Sections

Executive Summary

Generated automatically from trial data:

• Total trials completed
• Best objective value achieved
• Improvement percentage from initial design
• Key findings

Results Table

Metric	Initial	Final	Change
Objective 1	X	Y	Z%
Objective 2	X	Y	Z%

Best Solution

• Trial number
• All design variable values
• All objective values
• Constraint satisfaction status
• User attributes (source, validation status)

Design Variables Summary

Variable	Min	Max	Best Value	Sensitivity
var_1	0.0	10.0	5.23	High
var_2	0.0	20.0	12.87	Medium

Convergence Analysis

• Trials to 50% improvement
• Trials to 90% improvement
• Convergence rate assessment
• Phase breakdown (exploration, exploitation, refinement)

Recommendations

Auto-generated based on results:

• Further optimization suggestions
• Sensitivity observations
• Next steps for validation

---

Backend Implementation

File: atomizer-dashboard/backend/api/routes/optimization.py

@router.post("/studies/{study_id}/report/generate")
async def generate_report(study_id: str, format: str = "markdown"):
    """
    Generate comprehensive study report.

    Args:
        study_id: Study identifier
        format: Output format (markdown, json)

    Returns:
        Generated report content and file path
    """
    # Load configuration
    config = load_config(study_dir)

    # Query database for all trials
    trials = get_all_completed_trials(db)
    best_trial = get_best_trial(db)

    # Calculate metrics
    stats = calculate_statistics(trials)

    # Generate markdown
    report = generate_markdown_report(study_id, config, trials, best_trial, stats)

    # Save to file
    report_path = study_dir / "STUDY_REPORT.md"
    report_path.write_text(report)

    return {
        "success": True,
        "content": report,
        "path": str(report_path),
        "generated_at": datetime.now().isoformat()
    }

---

Report Template

The generated report follows this structure:

# {Study Name} - Optimization Report

**Generated:** {timestamp}
**Status:** {Completed/In Progress}

---

## Executive Summary

This optimization study completed **{n_trials} trials** and achieved a
**{improvement}%** improvement in the primary objective.

| Metric | Value |
|--------|-------|
| Total Trials | {n} |
| Best Value | {best} |
| Initial Value | {initial} |
| Improvement | {pct}% |

---

## Objectives

| Name | Direction | Weight | Best Value |
|------|-----------|--------|------------|
| {obj_name} | minimize | 1.0 | {value} |

---

## Design Variables

| Name | Min | Max | Best Value |
|------|-----|-----|------------|
| {var_name} | {min} | {max} | {best} |

---

## Best Solution

**Trial #{n}** achieved the optimal result.

### Parameters
- var_1: {value}
- var_2: {value}

### Objectives
- objective_1: {value}

### Constraints
- All constraints satisfied: Yes/No

---

## Convergence Analysis

- Initial best: {value} (trial 1)
- Final best: {value} (trial {n})
- 90% improvement reached at trial {n}

---

## Recommendations

1. Validate best solution with high-fidelity FEA
2. Consider sensitivity analysis around optimal design point
3. Check manufacturing feasibility of optimal parameters

---

*Generated by Atomizer Dashboard*

---

Prerequisites

Before generating a report:

• Study must have at least 1 completed trial
• study.db must exist in results directory
• optimization_config.json must be present

---

Error Handling

Error	Cause	Solution
"No trials found"	Empty database	Run optimization first
"Config not found"	Missing config file	Verify study setup
"Database locked"	Optimization running	Wait or pause first
"Invalid study"	Study path not found	Check study ID

---

Cross-References

• Preceded By: OP_04_ANALYZE_RESULTS
• Related: SYS_13_DASHBOARD
• Triggered By: Dashboard Report button

---

Version History

Version	Date	Changes
1.0	2026-01-06	Initial release - Dashboard integration