profiling-plan.md

Profiling Plan for C++ Core

Objective

The objective of this profiling plan is to identify performance bottlenecks within the C++ core of the AgentSimMiddleware early in the development cycle. By instrumenting key systems and collecting relevant metrics, we aim to gain insights necessary for optimization and ensuring the middleware meets its performance targets, especially for large-scale simulations.

Critical Systems for Profiling

The following areas are identified as critical for early profiling due to their direct impact on simulation performance and scalability:

1. Agent Update Loop (AgentContainer::update):

   • Description: This loop processes the fundamental updates for all active agents, including position, rotation, and potentially state transitions.
   • Metrics: Total execution time, average time per agent, per-frame execution time.

2. GOAP Planning (GOAPPlanner::plan):

   • Description: The process of agents deciding on goals and formulating plans (even a minimal one initially). This can become a significant bottleneck as the complexity of goals, actions, and the number of agents increases.
   • Metrics: Total planning time per frame, average planning time per agent, number of plans generated, search depth/nodes explored (for a more advanced planner).

3. FSM and Action Execution (StateMachine::updateAgentState, ActionExecutor::execute):

   • Description: The execution of chosen actions and their corresponding micro-behaviors, as managed by the State Machine and executed by the Action Executor.
   • Metrics: Total execution time for all agent FSMs and actions, average execution time per agent, call counts for specific actions.

4. Perception Queries:

   • Description: How agents gather information about their environment from the WorldSnapshot. This includes spatial queries (e.g., nearest neighbor, objects in radius) and property-based lookups.
   • Metrics: Total query time per frame, average query time per agent, latency of individual query types.

5. Memory Management (Agent Data Structures):

   • Description: Allocation, deallocation, and access patterns related to AgentData and other simulation-critical data. While memory pooling helps, understanding overall memory footprint and potential for cache misses is vital.
   • Metrics: Total memory allocated/deallocated per frame, peak memory usage, fragmentation (if custom allocators are used). (More advanced metrics like cache miss rates would require hardware performance counters.)

6. Multithreading Overhead:

   • Description: For the current std::thread based parallel processing, profiling will focus on thread creation/joining overhead and mutex contention (e.g., for command buffer access). For future custom job system implementations, profiling will expand to include synchronization costs, load balancing, and job queue management.
   • Metrics: Time spent in thread creation/joining, mutex lock contention, thread idle time.

Metrics to Track

For each critical system, the following general metrics will be collected:

• Execution Time: Elapsed time a specific code section or function takes to execute (e.g., using high-resolution timers).
• Call Counts: How many times a particular function or code path is invoked.
• Cycles/Instructions: (More advanced, requires platform-specific tools or hardware counters)
• Memory Footprint: Dynamic memory usage patterns.

Proposed Profiling Approach (Early Stage)

For early-stage profiling, a lightweight, custom instrumentation approach will be adopted to minimize overhead and provide immediate insights. This will involve:

1. High-Resolution Timers: Utilize C++ standard library's <chrono> for precise time measurements (std::chrono::high_resolution_clock).
2. Macros for Scoped Timing: Implement simple macros (e.g., PROFILE_SCOPE("FunctionName")) that automatically record entry and exit times for functions or code blocks.
3. Centralized Profiling Data Collection: A singleton Profiler class or similar mechanism will collect and aggregate timing data. This data can be logged to console, a file, or a simple in-memory buffer.
4. Conditional Compilation: All profiling code will be enclosed within preprocessor directives (e.g., #ifdef ENABLE_PROFILING) to ensure it can be completely stripped out in release builds.

Example Instrumentation (Conceptual)

// In a Profiler.h
#ifdef ENABLE_PROFILING
#define PROFILE_SCOPE(name) ScopedTimer timer_##name(name)
#else
#define PROFILE_SCOPE(name)
#endif

// In a function to profile
void AgentContainer::update(float deltaTime) {
    PROFILE_SCOPE("AgentContainer::update");
    // ... update logic ...
}

This early profiling plan will guide the iterative optimization process, allowing developers to focus efforts on areas that yield the greatest performance improvements for the AgentSimMiddleware.