Document order of growth of ECM methods

[arjo129]

Desired behavior

The EntityComponentManager (ECM) is the backbone of state management in Gazebo Sim. While the API is well-defined, the computational complexity (order of growth) of its core methods is not explicitly documented in the header files.

As simulations scale in complexity and entity count, developers need to understand the performance trade-offs of different ECM operations to ensure efficient system design.

An example of a performance bug found by @luca-della-vedova in #3362 shows that without such documentation, it is easy to introduce performance issues.

[strangerwhoisharborofdoom]

Hi @arjo129! I'm a first-year Robotics Engineering student and I'd like to contribute to this documentation task.

I'll document the computational complexity (order of growth) for the core EntityComponentManager methods in the header files. This will help developers make informed decisions about performance-critical code.

I'll start by:

1. Identifying all core ECM methods in the header files
2. Analyzing their implementations to determine time complexity
3. Adding clear documentation comments (e.g., /// \brief O(1), /// \brief O(n), etc.)
4. Referencing the performance bug [Performance] - Remove / Optimize EntitiesByComponents calls #3362 as an example of why this matters

Please let me know if there are any specific methods you'd like me to prioritize or any documentation style preferences!

Thanks!

[Sourav0607]

Hi, @arjo129 I'm a Mechatronics Master's student working with ROS2 and Gazebo Harmonic for my thesis and simulation projects. I'd like to work on this issue documenting the order of growth of ECM methods in the header files.
I've been working with the ECM through ROS2/Gazebo-based robot simulations and understand the performance impact this kind of documentation would have for developers scaling up simulations.
Is this issue still open for contribution? Happy to start by going through the ECM header files and annotating the core methods with their complexity. I'll reference #3362 as a concrete example of why this matters.

[Sumitb09]

Hi! I'm working on this issue. I've added \note comments documenting
the Big-O computational complexity of all public ECM methods in
EntityComponentManager.hh. Will be opening a PR shortly.

Methods documented:

• O(1) average: CreateEntity, EntityCount, HasEntity, ParentEntity,
  HasComponentType, EntityHasComponentType, RemoveComponent,
  CreateComponent, Component, ComponentData, SetComponentData,
  ComponentTypes, EntityByName
• O(k): EntityMatches (k = number of types to check)
• O(n): Each, EachNew, EachRemoved, EntityByComponents,
  EntitiesByComponents, ChildrenByComponents, Descendants

[Sourav0607]

Hi @arjo129 I'd like to work on this. I've submitted PR #3434 adding \complexity
documentation to all core public ECM methods including CreateEntity,
EntityCount, HasEntity, Component, Each, EachNoCache, EachNew,
EachRemoved, EntityByComponents, EntitiesByComponents, and Descendants.