This guide provides instructions on how to access and interpret the simulation logs, how they are structured by the `SimMonitor` class, and how to utilize the provided `visualize_log.py` script to analyze simulation data. Additionally, it offers guidance on creating your own scripts for custom analysis.
Simulation logs capture detailed telemetry and event data from each simulation run. These logs are essential for debugging, performance analysis, and understanding the behavior of agents within the simulation.
Logs are exported to the `Telemetry/Logs` folder in your operating system's [persistent data path](https://docs.unity3d.com/ScriptReference/Application-persistentDataPath.html).
`visualize_log.py` is an example script provided to help visualize and interpret the simulation logs. It is included in the `Tools` directory of the release download.
## Understanding Log Files and Directory Structure
### Log Directory Structure
Simulation logs are organized into timestamped directories within the `Logs` folder. Each simulation run generates a new directory named with the timestamp of the run.
For example:
```
Telemetry/
└── Logs/
├── 20241002_101305/
│ ├── sim_telemetry_20241002_101311.csv
│ ├── sim_events_20241002_101311.csv
│ │
│ ├── sim_telemetry_20241002_101306.csv
│ └── sim_events_20241002_101306.csv
├── 20241002_012122/
│ ├── sim_telemetry_20241002_012122.csv
│ └── sim_events_20241002_012122.csv
└── ...
```
Each simulation run produces two main CSV files:
- **Telemetry Log (`sim_telemetry_*.csv`)**: Contains detailed state information for each agent at each time step.
- **Event Log (`sim_events_*.csv`)**: Records significant events such as hits, misses, agent creation, and destruction.
### Log Files Generated by `SimMonitor`
The logging system is managed by the `SimMonitor` class in the simulation codebase.
```csharp
public class SimMonitor : MonoBehaviour
{
// Responsible for logging simulation data
// ...
}
```
**Key Responsibilities of `SimMonitor`:**
- Collecting agent state data at each simulation step.
- Writing telemetry data to `sim_telemetry_*.csv`.
- Recording significant events to `sim_events_*.csv`.
- Organizing logs into timestamped directories for each simulation run.
### Telemetry Log Structure
The telemetry log provides a snapshot of the simulation at each time step for every agent. Key columns include:
- **`Time`**: Simulation time at the log entry.
- **`AgentID`**: Unique identifier for each agent.
- **`AgentType`**: Type of the agent (e.g., interceptor, threat).
- **`AgentX`**, **`AgentY`**, **`AgentZ`**: Position coordinates of the agent.
- **`AgentStatus`**: Current status of the agent (e.g., active, destroyed).
### Event Log Structure
The event log records significant occurrences within the simulation. Key columns include:
- **`Time`**: Time when the event occurred.
- **`PositionX`**, **`PositionY`**, **`PositionZ`**: Position where the event occurred.
- **`EventType`**: Type of event (e.g., `HIT`, `MISS`, `NEW_THREAT`, `NEW_INTERCEPTOR`).
- **`Details`**: Additional details about the event.
## Running the `visualize_log.py` Script
The `visualize_log.py` script helps visualize agent trajectories and significant events in a 3D plot.
### Locating the Script
After downloading and extracting the release package, you can find the script at:
```
Tools/visualize_log.py
```
Make sure you have Python 3 installed on your system, along with the required libraries to run the script.
### Required Python Libraries
The script depends on the following Python libraries:
- **`pandas`**
- **`matplotlib`**
- **`numpy`**
You can install them using `pip`:
```bash
pip install pandas matplotlib numpy
```
### Usage
#### Navigate to the Tools Directory
Open a terminal or command prompt and navigate to the `Tools` directory:
```bash
cd path/to/Tools/
```
#### Run the Script
To visualize the most recent simulation logs:
```bash
python visualize_log.py
```
**What the Script Does:**
- **Automatically Finds the Latest Logs**: If no arguments are provided, it locates the most recent `sim_telemetry_*.csv` and `sim_events_*.csv` files.
- **Prints a Summary**: Outputs a summary of events, including total counts and timing of hits and misses.
- **Generates a 3D Plot**: Displays agent trajectories and marks events such as hits and misses.
#### Specifying Log Files Manually
You can also provide specific file paths as arguments:
