api_reference.md

🐜 Ant Stack API Reference

Complete API documentation for the Ant Stack modular scientific publication system.

---

📋 Table of Contents

• Core Package API
  • Analysis Module
  • Figures Module
  • Publishing Module
• Energy Analysis
• Statistical Methods
• Workload Modeling
• Figure Generation
• Publication Tools

---

📦 Core Package API

Analysis Module (antstack_core.analysis)

Energy Estimation (energy.py)

EnergyCoefficients Class

@dataclass
class EnergyCoefficients:
    """Energy coefficients for different computational operations."""

    # Core coefficients
    flops_pj: float = 1.0              # Energy per FLOP (picojoules)
    sram_pj_per_byte: float = 0.1      # SRAM access energy per byte
    dram_pj_per_byte: float = 20.0     # DRAM access energy per byte
    spike_aj: float = 1.0              # Neuromorphic spike energy (attojoules)

    # Physical coefficients
    body_per_joint_w: float = 2.0      # Actuation power per joint (watts)
    body_sensor_w_per_channel: float = 0.005  # Sensor power per channel (watts)
    baseline_w: float = 0.5            # Baseline system power (watts)

ComputeLoad Class

@dataclass
class ComputeLoad:
    """Computational workload specification."""

    flops: float = 0.0                 # Floating-point operations
    sram_bytes: float = 0.0           # SRAM memory access (bytes)
    dram_bytes: float = 0.0           # DRAM memory access (bytes)
    spikes: float = 0.0               # Neuromorphic spikes
    time_seconds: float = 1.0         # Execution time (seconds)

EnergyBreakdown Class

@dataclass
class EnergyBreakdown:
    """Detailed energy consumption breakdown."""

    # Computational energy
    compute_flops: float = 0.0         # FLOP energy
    compute_memory: float = 0.0        # Memory access energy
    compute_spikes: float = 0.0        # Neuromorphic energy

    # Physical energy
    actuation: float = 0.0             # Actuation energy
    sensing: float = 0.0               # Sensing energy
    baseline: float = 0.0              # Baseline energy

    # Computed properties
    @property
    def total(self) -> float:
        """Total energy consumption in joules."""
        return (self.compute_flops + self.compute_memory +
                self.compute_spikes + self.actuation +
                self.sensing + self.baseline)

Core Functions

def estimate_detailed_energy(
    load: ComputeLoad,
    coefficients: EnergyCoefficients
) -> EnergyBreakdown:
    """Estimate detailed energy consumption for a computational load.

    Args:
        load: Computational workload specification
        coefficients: Energy coefficients for the target hardware

    Returns:
        Detailed energy breakdown by component

    Example:
        >>> load = ComputeLoad(flops=1e9, sram_bytes=1e6, time_seconds=0.1)
        >>> coeffs = EnergyCoefficients()
        >>> energy = estimate_detailed_energy(load, coeffs)
        >>> print(f"Total energy: {energy.total:.2e} J")
    """

Statistical Methods (statistics.py)

Bootstrap Analysis

def bootstrap_mean_ci(
    data: List[float],
    n_bootstrap: int = 1000,
    confidence_level: float = 0.95,
    random_seed: Optional[int] = None
) -> Tuple[float, float, float]:
    """Calculate bootstrap confidence interval for the mean.

    Args:
        data: Input data samples
        n_bootstrap: Number of bootstrap samples
        confidence_level: Confidence level (0.0 to 1.0)
        random_seed: Random seed for reproducibility

    Returns:
        Tuple of (mean, lower_bound, upper_bound)

    Example:
        >>> data = [1.2, 1.5, 1.3, 1.8, 1.4, 1.6, 1.7]
        >>> mean, lower, upper = bootstrap_mean_ci(data, n_bootstrap=1000)
        >>> print(f"Mean: {mean:.2f} ({lower:.2f}, {upper:.2f})")
    """

Scaling Relationship Analysis

def analyze_scaling_relationship(
    x_values: np.ndarray,
    y_values: np.ndarray,
    log_transform: bool = True,
    confidence_level: float = 0.95
) -> Dict[str, Any]:
    """Analyze power-law scaling relationship between variables.

    Args:
        x_values: Independent variable values
        y_values: Dependent variable values
        log_transform: Whether to perform logarithmic transformation
        confidence_level: Confidence level for uncertainty quantification

    Returns:
        Dictionary containing scaling analysis results:
        - scaling_exponent: Power-law exponent
        - intercept: Scaling intercept
        - r_squared: Goodness of fit
        - confidence_interval: Uncertainty bounds

    Example:
        >>> x = np.array([1, 2, 4, 8, 16])
        >>> y = np.array([1, 2, 4, 8, 16])  # Perfect scaling
        >>> result = analyze_scaling_relationship(x, y)
        >>> print(f"Exponent: {result['scaling_exponent']:.2f}")
    """

Workload Modeling (workloads.py)

Body Workload Functions

def calculate_contact_complexity(
    joint_count: int,
    contact_points: int,
    friction_coefficient: float = 0.3,
    surface_normal_force: float = 10.0
) -> float:
    """Calculate complexity of contact dynamics for legged locomotion.

    Args:
        joint_count: Number of joints in the system
        contact_points: Number of contact points with the environment
        friction_coefficient: Coefficient of friction
        surface_normal_force: Normal force per contact point (N)

    Returns:
        Contact complexity metric

    Example:
        >>> complexity = calculate_contact_complexity(
        ...     joint_count=6, contact_points=4, friction_coefficient=0.3
        ... )
        >>> print(f"Contact complexity: {complexity:.2f}")
    """

Brain Workload Functions

def calculate_sparse_neural_complexity(
    neurons: int,
    connections: int,
    sparsity: float = 0.1,
    temporal_horizon: int = 10
) -> Dict[str, float]:
    """Calculate complexity of sparse neural network processing.

    Args:
        neurons: Number of neurons in the network
        connections: Number of synaptic connections
        sparsity: Connection sparsity (0.0 to 1.0)
        temporal_horizon: Temporal processing horizon

    Returns:
        Dictionary containing complexity metrics:
        - information_capacity: Information processing capacity
        - computational_density: Operations per neuron
        - temporal_complexity: Time-dependent processing complexity

    Example:
        >>> complexity = calculate_sparse_neural_complexity(
        ...     neurons=1000, connections=10000, sparsity=0.1
        ... )
        >>> print(f"Capacity: {complexity['information_capacity']:.2e}")
    """

Mind Workload Functions

def calculate_active_inference_complexity(
    state_space_size: int,
    observation_space_size: int,
    planning_horizon: int,
    branching_factor: int = 3
) -> Dict[str, float]:
    """Calculate complexity of active inference planning.

    Args:
        state_space_size: Size of the state space
        observation_space_size: Size of the observation space
        planning_horizon: Temporal planning horizon
        branching_factor: Decision branching factor

    Returns:
        Dictionary containing complexity metrics:
        - state_uncertainty: Uncertainty in state estimation
        - planning_complexity: Computational complexity of planning
        - information_efficiency: Information processing efficiency

    Example:
        >>> complexity = calculate_active_inference_complexity(
        ...     state_space_size=100, observation_space_size=50,
        ...     planning_horizon=5, branching_factor=3
        ... )
        >>> print(f"Planning complexity: {complexity['planning_complexity']:.2e}")
    """

---

🎨 Figure Generation API

Figures Module (antstack_core.figures)

Plotting Utilities (plots.py)

Scatter Plot Function

def create_scatter_plot(
    x_data: np.ndarray,
    y_data: np.ndarray,
    x_label: str = "X",
    y_label: str = "Y",
    title: str = "Scatter Plot",
    color: str = "blue",
    alpha: float = 0.7,
    figsize: Tuple[float, float] = (8, 6)
) -> plt.Figure:
    """Create publication-quality scatter plot.

    Args:
        x_data: X-axis data
        y_data: Y-axis data
        x_label: X-axis label
        y_label: Y-axis label
        title: Plot title
        color: Point color
        alpha: Point transparency
        figsize: Figure size (width, height)

    Returns:
        Matplotlib Figure object

    Example:
        >>> x = np.random.normal(0, 1, 100)
        >>> y = 2*x + np.random.normal(0, 0.5, 100)
        >>> fig = create_scatter_plot(x, y, "Input", "Output", "Linear Relationship")
        >>> plt.savefig("scatter_plot.png")
    """

Scaling Plot Function

def create_scaling_plot(
    x_values: List[float],
    y_values: List[float],
    x_label: str = "Scale Parameter",
    y_label: str = "Performance Metric",
    title: str = "Scaling Analysis",
    scaling_exponent: Optional[float] = None,
    confidence_interval: Optional[Tuple[float, float]] = None,
    figsize: Tuple[float, float] = (10, 8)
) -> plt.Figure:
    """Create scaling relationship plot with power-law fit.

    Args:
        x_values: Independent variable values
        y_values: Dependent variable values
        x_label: X-axis label
        y_label: Y-axis label
        title: Plot title
        scaling_exponent: Fitted scaling exponent (optional)
        confidence_interval: Confidence interval for exponent (optional)
        figsize: Figure size

    Returns:
        Matplotlib Figure object with scaling analysis

    Example:
        >>> x_vals = [1, 2, 4, 8, 16, 32]
        >>> y_vals = [1.0, 1.8, 3.2, 5.8, 10.4, 18.8]  # ~0.8 scaling
        >>> fig = create_scaling_plot(x_vals, y_vals,
        ...                          scaling_exponent=0.8,
        ...                          confidence_interval=(0.75, 0.85))
    """

Mermaid Diagram Processing (mermaid.py)

Diagram Rendering Function

def render_mermaid_diagram(
    mermaid_code: str,
    output_path: Union[str, Path],
    format: str = "png",
    width: Optional[int] = None,
    height: Optional[int] = None,
    background_color: str = "white"
) -> bool:
    """Render Mermaid diagram to image file.

    Args:
        mermaid_code: Mermaid diagram source code
        output_path: Output file path
        format: Output format ("png", "svg", "pdf")
        width: Diagram width (optional)
        height: Diagram height (optional)
        background_color: Background color

    Returns:
        True if rendering successful, False otherwise

    Example:
        >>> diagram = '''
        ... graph TD
        ...     A[Start] --> B{Decision}
        ...     B -->|Yes| C[Action 1]
        ...     B -->|No| D[Action 2]
        ... '''
        >>> success = render_mermaid_diagram(diagram, "flowchart.png")
    """

---

📊 Advanced Analysis API

Enhanced Estimators (enhanced_estimators.py)

Enhanced Energy Estimator Class

class EnhancedEnergyEstimator:
    """Enhanced energy estimator with comprehensive analysis capabilities.

    Provides detailed energy estimation, scaling analysis, and theoretical
    limit comparisons for all Ant Stack modules.
    """

    def __init__(self, coefficients: EnergyCoefficients):
        """Initialize estimator with energy coefficients.

        Args:
            coefficients: EnergyCoefficients instance with device parameters
        """

    def analyze_body_scaling(
        self,
        j_values: List[int],
        base_params: Dict[str, Any]
    ) -> ModuleScalingData:
        """Analyze AntBody energy scaling across joint counts.

        Args:
            j_values: List of joint counts to analyze
            base_params: Base parameters for body analysis

        Returns:
            ModuleScalingData with scaling analysis results
        """

    def analyze_brain_scaling(
        self,
        c_values: List[int],
        base_params: Dict[str, Any]
    ) -> ModuleScalingData:
        """Analyze AntBrain energy scaling across channel counts.

        Args:
            c_values: List of channel counts to analyze
            base_params: Base parameters for brain analysis

        Returns:
            ModuleScalingData with scaling analysis results
        """

    def analyze_mind_scaling(
        self,
        h_values: List[int],
        base_params: Dict[str, Any]
    ) -> ModuleScalingData:
        """Analyze AntMind energy scaling across planning horizons.

        Args:
            h_values: List of planning horizons to analyze
            base_params: Base parameters for mind analysis

        Returns:
            ModuleScalingData with scaling analysis results
        """

Veridical Reporting (veridical_reporting.py)

Veridical Reporter Class

class VeridicalReporter:
    """Comprehensive veridical reporting system.

    Provides principled, evidence-based scientific reporting with
    uncertainty quantification and reproducibility tracking.
    """

    def generate_empirical_evidence(
        self,
        measurements: Dict[str, Any],
        statistical_tests: Dict[str, Any],
        confidence_level: float = 0.95
    ) -> EmpiricalEvidence:
        """Generate comprehensive empirical evidence report.

        Args:
            measurements: Raw measurement data
            statistical_tests: Statistical analysis results
            confidence_level: Confidence level for uncertainty quantification

        Returns:
            EmpiricalEvidence object with validated findings
        """

    def create_case_study(
        self,
        system_description: str,
        experimental_setup: Dict[str, Any],
        results: Dict[str, Any],
        implications: List[str]
    ) -> CaseStudy:
        """Create detailed case study with scientific rigor.

        Args:
            system_description: Description of the system under study
            experimental_setup: Experimental methodology and parameters
            results: Experimental results and findings
            implications: Scientific and practical implications

        Returns:
            CaseStudy object with comprehensive analysis
        """

---

🧪 Testing Framework API

Test Coverage Statistics

Module	Coverage	Status	Test Count
veridical_reporting.py	100%	✅ Complete	18 tests
scaling_analysis.py	73%	✅ Complete	23 tests
enhanced_complexity_analysis.py	74%	✅ Complete	30 tests
behavioral.py	58%	✅ Complete	27 tests
enhanced_estimators.py	100%	✅ Complete	24 tests
key_numbers.py	52%	✅ Complete	34 tests
Total	~70%	✅ Good Coverage	200+ tests

Test Organization

tests/
├── antstack_core/                    # Core package tests
│   ├── test_energy.py                # Energy estimation tests
│   ├── test_statistics.py            # Statistical method tests
│   ├── test_workloads.py             # Workload modeling tests
│   ├── test_enhanced_estimators.py   # Advanced estimation tests
│   ├── test_key_numbers.py           # Key numbers integration tests
│   └── test_figures.py               # Figure generation tests
├── complexity_energetics/           # Paper-specific tests
│   ├── test_ce.py                    # Legacy tests
│   ├── test_enhanced_ce.py           # Enhanced complexity tests
│   └── test_integration_workflows.py # Integration tests
└── test_core_refactor.py             # Modular system tests

---

📈 Performance Benchmarks

Computational Performance

Operation	Performance	Units
Energy Estimation	< 1ms	per workload
Bootstrap CI (1000)	~50ms	per analysis
Scaling Analysis	~10ms	per fit
Mermaid Rendering	~2s	per diagram
PDF Generation	~30s	per paper

Memory Usage

Component	Memory	Notes
Core Package	~50MB	Base memory usage
Large Dataset	~200MB	With bootstrap analysis
Figure Generation	~100MB	Peak during rendering
PDF Build	~500MB	Peak during compilation

---

🔗 Integration Examples

Complete Analysis Workflow

from antstack_core.analysis.energy import EnergyCoefficients, ComputeLoad, estimate_detailed_energy
from antstack_core.analysis.statistics import bootstrap_mean_ci, analyze_scaling_relationship
from antstack_core.analysis.enhanced_estimators import EnhancedEnergyEstimator

# 1. Define energy coefficients for target hardware
coeffs = EnergyCoefficients(
    flops_pj=1.5,           # 1.5 pJ per FLOP
    sram_pj_per_byte=0.2,   # 0.2 pJ per SRAM byte
    dram_pj_per_byte=25.0,  # 25 pJ per DRAM byte
    baseline_w=0.8          # 0.8W baseline power
)

# 2. Define computational workload
workload = ComputeLoad(
    flops=1e9,              # 1 billion FLOPs
    sram_bytes=1e6,         # 1 MB SRAM access
    dram_bytes=1e8,         # 100 MB DRAM access
    time_seconds=0.1        # 100ms execution time
)

# 3. Estimate detailed energy consumption
energy_breakdown = estimate_detailed_energy(workload, coeffs)
print(f"Total energy: {energy_breakdown.total:.2e} J")

# 4. Perform scaling analysis
x_vals = [1, 2, 4, 8, 16, 32]
y_vals = [1.0, 1.8, 3.2, 5.8, 10.4, 18.8]

scaling_result = analyze_scaling_relationship(
    np.array(x_vals),
    np.array(y_vals),
    confidence_level=0.95
)
print(f"Scaling exponent: {scaling_result['scaling_exponent']:.2f}")

# 5. Generate comprehensive analysis report
estimator = EnhancedEnergyEstimator(coeffs)
analysis = estimator.perform_comprehensive_analysis(
    body_params={'v': 1.0, 'm': 0.001, 'L': 0.01, 'dt': 0.01, 'g': 9.81},
    brain_params={'C': 100, 'sparsity': 0.1, 'dt': 0.01},
    mind_params={'H': 5, 'B': 3, 'dt': 0.01}
)

print(f"Total system energy: {analysis.total_energy_per_decision_j:.2e} J/decision")

---

📚 References & Citations

Scientific Literature

• Energy Estimation: Horowitz, M. "Energy dissipation in VLSI circuits" (1993)
• Bootstrap Methods: Efron, B. "Bootstrap methods: Another look at the jackknife" (1979)
• Scaling Analysis: Barabasi, A.-L. "Scale-free networks" (2003)
• Active Inference: Friston, K. "Active inference: A process theory" (2017)

Technical References

• NumPy: Harris et al. "Array programming with NumPy" (2020)
• Matplotlib: Hunter, J. "Matplotlib: A 2D graphics environment" (2007)
• SciPy: Virtanen et al. "SciPy 1.0: fundamental algorithms" (2020)

---

This API reference is automatically generated from the codebase. For the latest updates, see the source code documentation.