Coverage for pybeepop/engine_interface.py: 58%
26 statements
« prev ^ index » next coverage.py v7.11.0, created at 2025-10-30 13:34 +0000
1"""
2Engine interface protocol for PyBeePop dual-engine architecture.
4This module defines the BeepopEngineInterface protocol that both C++ and Python
5engines must implement to be compatible with the PyBeePop wrapper.
6"""
8from typing import Protocol, Dict, Optional
9import pandas as pd
12class BeepopEngineInterface(Protocol):
13 """
14 Protocol defining the interface that all BeePop simulation engines must implement.
16 This protocol ensures that both the C++ engine (via BeePopModel) and the pure
17 Python engine (via beepop.BeePop) can be used interchangeably through adapters.
19 All methods should return consistent types regardless of underlying engine.
21 Note: Initialization happens in __init__(), not via a separate initialize_model() method.
22 """
24 engine_type: str # 'cpp' or 'python'
26 def set_parameters(self, parameters: Dict[str, str]) -> Dict[str, str]:
27 """
28 Set simulation parameters from a dictionary.
30 Args:
31 parameters: Dictionary of parameter name -> value pairs.
32 Example: {"ICWorkerAdults": "10000", "SimStart": "04/01/2023"}
34 Returns:
35 Dict[str, str]: Dictionary of parameters that were successfully set.
36 """
37 ...
39 def get_parameters(self) -> Dict[str, str]:
40 """
41 Get currently set parameters.
43 Returns:
44 Dict[str, str]: Dictionary of current parameter values.
45 """
46 ...
48 def load_parameter_file(self, file_path: str) -> bool:
49 """
50 Load parameters from a text file.
52 Args:
53 file_path: Path to parameter file (format: parameter=value per line).
55 Returns:
56 bool: True if file loaded successfully, False otherwise.
57 """
58 ...
60 def load_weather_file(self, file_path: str) -> bool:
61 """
62 Load weather data from a CSV or text file.
64 Args:
65 file_path: Path to weather file.
67 Returns:
68 bool: True if file loaded successfully, False otherwise.
69 """
70 ...
72 def load_residue_file(self, file_path: str) -> bool:
73 """
74 Load pesticide residue/contamination data from a file.
76 Args:
77 file_path: Path to residue file.
79 Returns:
80 bool: True if file loaded successfully, False otherwise.
81 """
82 ...
84 def set_latitude(self, latitude: float) -> bool:
85 """
86 Set geographic latitude for daylight calculations.
88 Args:
89 latitude: Latitude in decimal degrees (-90 to 90).
91 Returns:
92 bool: True if latitude set successfully, False otherwise.
93 """
94 ...
96 def run_simulation(self) -> Optional[pd.DataFrame]:
97 """
98 Execute the simulation and return results.
100 Returns:
101 pd.DataFrame: DataFrame with simulation results (44 columns), or None if failed.
102 """
103 ...
105 def get_error_log(self) -> str:
106 """
107 Get error messages from the simulation session.
109 Returns:
110 str: Error log as newline-separated string.
111 """
112 ...
114 def get_info_log(self) -> str:
115 """
116 Get informational messages from the simulation session.
118 Returns:
119 str: Info log as newline-separated string.
120 """
121 ...
123 def get_version(self) -> str:
124 """
125 Get the engine version string.
127 Returns:
128 str: Version string (e.g., "1.15.25").
129 """
130 ...
132 def cleanup(self) -> None:
133 """
134 Clean up resources and close connections.
136 This method should be idempotent and safe to call multiple times.
137 """
138 ...