{
  "name": "Factory",
  "main": {
    "name": "Factory",
    "namespace": "sofa::helper",
    "module": "Sofa.framework.Helper",
    "include": "sofa/helper/Factory.h",
    "doc": "",
    "inherits": [
      "Intersection"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "registerCreator",
        "return_type": "bool",
        "params": [
          {
            "name": "key",
            "type": "Key"
          },
          {
            "name": "creator",
            "type": "Creator *"
          },
          {
            "name": "multi",
            "type": "bool"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "createAnyObject",
        "return_type": "ObjectPtr",
        "params": [
          {
            "name": "arg",
            "type": "Argument"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "uniqueKeys",
        "return_type": "void",
        "params": [
          {
            "name": "out",
            "type": "OutIterator"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "hasKey",
        "return_type": "bool",
        "params": [
          {
            "name": "key",
            "type": "Key"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "duplicateEntry",
        "return_type": "bool",
        "params": [
          {
            "name": "existing",
            "type": "Key"
          },
          {
            "name": "duplicate",
            "type": "Key"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "resetEntry",
        "return_type": "bool",
        "params": [
          {
            "name": "existingKey",
            "type": "Key"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getInstance",
        "return_type": "Factory<Key, Object, Argument, ObjectPtr> *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "CreateObject",
        "return_type": "ObjectPtr",
        "params": [
          {
            "name": "key",
            "type": "Key"
          },
          {
            "name": "arg",
            "type": "Argument"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "CreateAnyObject",
        "return_type": "ObjectPtr",
        "params": [
          {
            "name": "arg",
            "type": "Argument"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "HasKey",
        "return_type": "bool",
        "params": [
          {
            "name": "key",
            "type": "Key"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "DuplicateEntry",
        "return_type": "bool",
        "params": [
          {
            "name": "existing",
            "type": "Key"
          },
          {
            "name": "duplicate",
            "type": "Key"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "ResetEntry",
        "return_type": "bool",
        "params": [
          {
            "name": "existing",
            "type": "Key"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "begin",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "end",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `Factory` class in the SOFA framework is a template-based mechanism designed to manage and create instances of objects dynamically based on registered keys. Its primary role is to facilitate object creation through a factory pattern, allowing registration of creators for different object types with specific keys. This component is essential for managing polymorphic behavior and dynamic instantiation across various components within SOFA simulations.\n\n### Interactions with Other Components\n- **Registration**: The `registerCreator` method allows other components or plugins to register their own creators (derived from `BaseCreator`) which can then be used to instantiate objects based on specific keys. This enables a flexible and extensible system for adding new object types without modifying existing code.\n- **Object Creation**: Methods such as `createObject` and `CreateAnyObject` are used by other components to create instances of registered classes dynamically during runtime. This is crucial for simulation setups where different behaviors or models need to be instantiated based on configuration parameters.\n\n### Practical Usage Guidance\n- **Registering Creators**: Use the `registerCreator` method to register creators that can instantiate objects given a specific key and optional arguments.\n- **Creating Objects**: Utilize methods like `createObject`, `CreateAnyObject`, or static methods such as `HasKey`, `DuplicateEntry`, and `ResetEntry` for managing object creation and factory state. These methods provide mechanisms to check for registered keys, duplicate entries, and reset specific entries within the registry.\n- **Factory Singleton**: The `getInstance` method provides a singleton instance of the Factory, ensuring consistent and centralized management of object creation throughout the simulation."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of the `Factory` Component in SOFA Framework\n\n## Overview\nThe `Factory` class serves as a template-based mechanism for managing dynamic object instantiation within the SOFA framework. It leverages the factory pattern, which is a creational design pattern used to encapsulate and delegate the creation process of objects.\n\n## Key Components and Operations\n### 1. **Registration Mechanism**\n- The `Factory` class allows registration of creators (objects that implement the `BaseCreator` interface) with specific keys. This mechanism is pivotal for enabling polymorphic behavior, allowing different object types to be instantiated based on these registered keys.\n\n#### Mathematical Representation:\nLet \\(\\mathcal{F}\\) denote the set of all factories in the system and \\(\textbf{C} = \\{c_i\\}_{i=1}^{N_c}\\) represent a collection of creators, where each creator \\(c_i\\) is associated with an object type and a unique key \\(k_i\\).\n\nThe registration process can be represented as:\n\\[\n\\textbf{F} = (\\mathcal{K}, \\mathcal{C})\n\\]\nwhere \\(\textbf{F}\\) is the factory instance, \\(\textcal{K}\\) is a set of keys, and \\(\textcal{C}\\) is the corresponding set of creators. Each key-to-creator mapping can be represented as:\n\\[\nk_i: c_i\n\\]\nfor each registered creator.\n\n### 2. **Object Creation**\nThe factory provides methods to instantiate objects based on registered keys. The `createObject` and `CreateAnyObject` functions utilize the registry to select an appropriate creator for object instantiation.\n\n#### Mathematical Representation:\nLet \\(\\mathcal{O}\\) represent the set of all possible objects that can be created by the factory.\nThe function \\(\textbf{f}: k_i \rightarrow o_j\\) represents the process where a key \\(k_i\\) maps to an object instance \\(o_j\\).\n\nFor example, if a creator registered with key \\(k_i\\) is responsible for creating objects of type \\(O_j\\), then:\n\\[\no_j = f(k_i)\n\\]\nwhere \\(\textbf{f}\\) is the creation function associated with the specific creator.\n\n### 3. **Management and Utility Functions**\nThe `Factory` class provides additional methods such as `HasKey`, `DuplicateEntry`, and `ResetEntry` to manage the registry effectively.\n- `HasKey(k)` checks if a key \\(k\\) is present in the factory's registry, mathematically represented as:\n\\[\n\\text{HasKey}(k) =\n\\begin{cases}\n  1 & \\text{if } k \\in \textbf{K}\\\\\n  0 & \\text{otherwise}\\end{cases}\n\\]\n- `DuplicateEntry(k, d)` allows for duplicating an entry in the registry with a new key \\(d\\) if not already present.\n\n#### Mathematical Representation:\nFor duplication of entry, consider two keys \\(k\\) and \\(d\\):\n\\[\nk: c_i \rightarrow d: c_i\n\\]\nas long as \\(\text{HasKey}(d) = 0\\).\n- `ResetEntry(k)` removes a registration from the factory's registry.\n\n#### Mathematical Representation:\nThe removal operation can be represented as removing \\(k:c_i\\) pair from the mapping, effectively:\n\\[\nk: c_i \\rightarrow \text{Null}\n\\]\nwhere Null signifies the absence of such an entry in the registry.\n\n## Physical Interpretation\nIn the context of physical simulations (e.g., biomechanics, robotics), the `Factory` component is crucial for creating and managing different types of objects (such as forces, constraints, or materials) dynamically based on simulation requirements. The registration mechanism allows plugins or external modules to extend the framework by adding new object types without modifying the core system. This flexibility ensures that simulations can be customized and extended efficiently.\n\n## Conclusion\nThe `Factory` component in SOFA is a fundamental building block for enabling dynamic and flexible object creation within the simulation environment. Through its registration, creation, and management mechanisms, it supports polymorphic behavior and extensibility of the framework."
  },
  "summary": {
    "abstract": "The `Factory` component manages dynamic object instantiation in SOFA by registering creators with specific keys and providing methods to create objects based on these keys.",
    "sheet": "# Factory\n\n## Overview\nThe `Factory` class serves as a template-based mechanism for managing dynamic object instantiation within the SOFA framework. It leverages the factory pattern, allowing registration of creators (derived from `BaseCreator`) with specific keys and enabling polymorphic behavior during runtime.\n\n## Parameters and Data\n- **registerCreator**: Registers a creator with a specific key (`Key`), a pointer to the creator function (`Creator *`), and an optional boolean flag for multi-registration (`bool`).\n- **createAnyObject**: Creates an object based on provided arguments (`Argument`) and returns an `ObjectPtr`.\n- **uniqueKeys**: Outputs unique keys from the registry using an iterator (`OutIterator`).\n- **hasKey**: Checks if a specific key exists in the registry (`Key`).\n- **duplicateEntry**: Duplicates an entry in the registry with a new key, provided it does not already exist (`existing: Key`, `duplicate: Key`).\n- **resetEntry**: Resets an existing entry in the registry by removing its association (`existingKey: Key`).\n\n## Dependencies and Connections\nThe `Factory` component is typically used by other components or plugins to register their own creators and instantiate objects dynamically. It interacts with various parts of the SOFA scene graph, enabling flexible object creation based on simulation requirements.\n\n## Practical Notes\n- **Registering Creators**: Use the `registerCreator` method to add new object types without modifying existing code.\n- **Creating Objects**: Utilize methods like `createObject`, `CreateAnyObject`, and static methods such as `HasKey`, `DuplicateEntry`, and `ResetEntry` for managing object creation and factory state.\n- **Factory Singleton**: The `getInstance` method provides a singleton instance of the Factory, ensuring consistent management of object creation throughout the simulation."
  }
}