AGENTS.md@infrastructure/scientific · git:20260606.243a3c4 · 2026-06-06 · sha256 90c8a2235b0f8889
AGENTS.md@infrastructure/scientific git:20260606.243a3c4A

Name: AGENTS.md@infrastructure/scientific
Author: docxology
Immutable. This exact content is served forever at /api/v1/blob/90c8a2235b0f8889.
# Scientific Module

## Purpose

The Scientific module provides utilities and best practices for developing scientific computing software. It includes numerical stability checking, performance benchmarking, research workflow templates, and compliance validation for scientific implementations.

## Architecture

### Modular Structure

The scientific module has been refactored into focused submodules for better organization:

```mermaid
flowchart TB
    SCI[/infrastructure/scientific//]
    SCI --> INIT[__init__.py<br/>Public API exports]
    SCI --> STAB[stability.py<br/>Numerical stability checking]
    SCI --> BEN[benchmarking.py<br/>Performance benchmarking]
    SCI --> CONF[confirmation.py<br/>Improvement confirmation]
    SCI --> DOC[documentation.py<br/>Scientific documentation generation]
    SCI --> VAL[validation.py<br/>Implementation validation]
    SCI --> TPL[templates.py<br/>Module &amp; workflow templates]

    classDef d fill:#0f172a,stroke:#0f172a,color:#fff
    classDef f fill:#1e3a8a,stroke:#0f172a,color:#fff
    class SCI d
    class INIT,STAB,BEN,CONF,DOC,VAL,TPL f
```

**stability.py** (~100 lines)
- `check_numerical_stability()` - Test algorithmic stability across input ranges
- `StabilityTest` dataclass - Stability test results with recommendations

**benchmarking.py** (~200 lines)
- `benchmark_function()` - Performance measurement with memory tracking
- `format_benchmark_report()` - performance analysis
- `BenchmarkResult` dataclass - Benchmark results with timing and memory

**confirmation.py**
- `confirm_improvement()` - Confirm a candidate beats a baseline metric beyond the noise band
- `Confirmation` dataclass - Result with `candidate_mean`, `baseline_metric`, `delta`, `noise_band`, `confirmed`

**documentation.py** (~120 lines)
- `generate_scientific_documentation()` - Function documentation from signatures
- `generate_api_documentation()` - Module-level API documentation

**validation.py** (~300 lines)
- `validate_scientific_implementation()` - Test case validation
- `validate_scientific_best_practices()` - Module-level compliance checking
- `check_research_compliance()` - Research software standards verification

**templates.py** (~220 lines)
- `create_scientific_module_template()` - Module boilerplate with best practices
- `create_scientific_test_suite()` - test suite templates
- `create_scientific_workflow_template()` - Reproducible workflow templates

## Key Features

### Numerical Stability
```python
# Import from main module (recommended)
from infrastructure.scientific import check_numerical_stability, StabilityTest

# Or import from specific module
from infrastructure.scientific.stability import check_numerical_stability

stability = check_numerical_stability(
    your_algorithm,
    test_inputs,
    tolerance=1e-12
)
```

### Performance Benchmarking
```python
# Import from main module (recommended)
from infrastructure.scientific import benchmark_function, format_benchmark_report

# Or import from specific module
from infrastructure.scientific.benchmarking import benchmark_function

benchmark = benchmark_function(
    your_function,
    test_inputs,
    iterations=100
)
```

### Improvement Confirmation
```python
# Import from main module (recommended)
from infrastructure.scientific import confirm_improvement, Confirmation

# Or import from specific module
from infrastructure.scientific.confirmation import confirm_improvement

result = confirm_improvement(
    evaluate=your_evaluator,   # (params, seed) -> metric
    candidate=(0.1, 0.2),
    baseline_metric=1.0,
    seeds=[0, 1, 2, 3],
    noise_scale=0.05,
    sigma=2.0,
)
print(result.delta, result.noise_band, result.confirmed)
```

### Scientific Documentation
```python
# Import from main module (recommended)
from infrastructure.scientific import generate_scientific_documentation, generate_api_documentation

# Or import from specific module
from infrastructure.scientific.documentation import generate_scientific_documentation

docs = generate_scientific_documentation(your_function)
```

### Best Practices Validation
```python
# Import from main module (recommended)
from infrastructure.scientific import validate_scientific_best_practices, check_research_compliance

# Or import from specific module
from infrastructure.scientific.validation import validate_scientific_best_practices

report = validate_scientific_best_practices(your_module)
```

### Module Templates
```python
# Import from main module (recommended)
from infrastructure.scientific import (
    create_scientific_module_template,
    create_scientific_test_suite,
    create_scientific_workflow_template,
)

# Or import from specific module
from infrastructure.scientific.templates import create_scientific_module_template

template = create_scientific_module_template("my_algorithm")
```

## Testing

Run scientific tests with:
```bash
uv run pytest tests/infra_tests/scientific/
```

## Configuration

No specific configuration required. All scientific utilities operate with sensible defaults.

## Integration

Scientific module is used by:
- Research algorithm validation
- Performance optimization workflows
- Scientific package development
- Best practices enforcement

## Troubleshooting

### Stability Tests Fail

**Issue**: `check_numerical_stability()` reports instability.

**Solutions**:
- Review tolerance settings (may be too strict)
- Check input ranges are appropriate for algorithm
- Verify algorithm implementation is correct
- Review numerical precision requirements
- Consider algorithm modifications for better stability

### Benchmarking Errors

**Issue**: `benchmark_function()` fails or returns unexpected results.

**Solutions**:
- Verify function is callable and accepts test inputs
- Check test inputs are valid for function
- Ensure sufficient system resources (memory, CPU)
- Review iteration count (may be too high)
- Check for side effects affecting measurements

### Documentation Generation Fails

**Issue**: `generate_scientific_documentation()` produces incomplete docs.

**Solutions**:
- Verify function has proper docstrings
- Check function signature is parseable
- Ensure type hints are present
- Review AST parsing for complex signatures
- Check for syntax errors in source code

### Validation Reports Issues

**Issue**: `validate_scientific_best_practices()` reports unexpected failures.

**Solutions**:
- Review validation criteria for your use case
- Check that module follows expected structure
- Verify test coverage meets requirements
- Ensure documentation is - Review validation configuration

### Template Generation Errors

**Issue**: `create_scientific_module_template()` creates invalid code.

**Solutions**:
- Verify module name follows Python naming conventions
- Check template parameters are valid
- Review generated code for syntax errors
- Ensure output directory is writable
- Test generated templates before use

## Best Practices

### Numerical Stability

- **Test Early**: Check stability during algorithm development
- **Use Appropriate Tolerances**: Set tolerances based on problem requirements
- **Test Edge Cases**: Include boundary conditions in stability tests
- **Document Assumptions**: Document numerical assumptions clearly

### Performance Benchmarking

- **Warm Up**: Allow warm-up iterations before measurement
- **Multiple Runs**: Run benchmarks multiple times for reliability
- **Control Environment**: Minimize system load during benchmarking
- **Track Trends**: Monitor performance over time

### Scientific Documentation

- **Docstrings**: Include purpose, parameters, returns, and examples
- **Type Hints**: Use type hints for all function signatures
- **Examples**: Provide working code examples
- **Mathematical Notation**: Document mathematical formulations clearly

### Best Practices Validation

- **Follow Standards**: Adhere to scientific computing best practices
- **Test Coverage**: Maintain high test coverage
- **Documentation**: Keep documentation current with code
- **Code Quality**: Follow PEP 8 and scientific computing conventions

### Module Templates

- **Use Templates**: Start modules from templates
- **Customize Appropriately**: Adapt templates to specific needs
- **Maintain Consistency**: Follow template structure across modules
- **Update Templates**: Keep templates current with best practices

### Research Compliance

- **Reproducibility**: Ensure all code is reproducible
- **Version Control**: Track all code changes
- **Documentation**: Document algorithms and methods thoroughly
- **Testing**: Test all scientific code comprehensively

## See Also

- [README.md](README.md) - Quick reference guide
- [`core/`](../core/) - Foundation utilities
- [`core/source_improve.py`](../core/source_improve.py) - AST-based source improvement (orchestrated by [`scripts/batch_cogsec_improve.py`](../../scripts/batch_cogsec_improve.py))