.. _python_api_draft:

*****
Draft
*****


A draft is an isolated, in-memory snapshot of an asset's entity information. It lets you inspect and modify entities (surfaces, edges, volumes, body groups, etc.) locally without mutating the cloud asset.

.. currentmodule:: flow360.component.simulation.draft_context

.. autosummary::
   :toctree: _autosummary
   :template: class_no_pydantic.rst

   DraftContext


The draft is created using the `create_draft()` function. It is meant to be used with the `with` statement to create a context manager.

.. currentmodule:: flow360

.. code-block:: python

    with fl.create_draft(new_run_from=geometry) as draft:
        ...

.. autosummary::
   :toctree: _autosummary

   create_draft

The draft is responsible primarily for the following:

- grouping **faces**, **edges** and **body groups**
- keeping track of all the existen entities 
- managing **mirror** actions
- managing **coordinate systems**

Access properties
-----------------

The properties of the :class:`~flow360.component.simulation.draft_context.DraftContext` that store the geometric entities within the draft are listed below. 
The entities within those properties can be accessed by name or pattern with the only exception being the imported geometries and surfaces, which can be accessed by index.

.. currentmodule:: flow360.component.simulation.draft_context

.. autosummary::
   :toctree: _autosummary
   :template: property.rst

   DraftContext.body_groups
   DraftContext.surfaces
   DraftContext.mirrored_body_groups
   DraftContext.mirrored_surfaces
   DraftContext.edges
   DraftContext.volumes
   DraftContext.boxes
   DraftContext.cylinders
   DraftContext.imported_geometries
   DraftContext.imported_surfaces

Management properties
---------------------

Managing **mirror** actions and **coordinate systems** is done through the following properties.

.. autosummary::
   :toctree: _autosummary
   :template: property.rst

   DraftContext.coordinate_systems
   DraftContext.mirror


Those properties provide access to relevant managers. 

.. currentmodule:: flow360.component.simulation.draft_context

.. autosummary::
   :toctree: _autosummary
   :template: class_no_pydantic.rst

   ~coordinate_system_manager.CoordinateSystemManager
   ~mirror.MirrorManager
   
Actions and objects registered through those managers can be modified by directly accessing them through the manager objects.

**Example**: geometric parameter sensitivity study

.. code-block:: python

    with draft:
        draft.coordinate_systems.assign(
            entities=draft.body_groups["body_group_1"],
            coordinate_system=fl.CoordinateSystem(
                name="body_group_1_translation",
                origin=[0, 0, 0] * fl.u.mm,
                axis_of_rotation=(0, 0, 1),
                angle_of_rotation=0 * fl.u.deg,
                scale=(1.0, 1.0, 1.0),
                translation=[20, 0, 0] * fl.u.mm
            )
        )

        prj.run_case(...)

        draft.coordinate_systems.get_by_name("body_group_1_translation").angle_of_rotation = 5*fl.u.deg

        prj.run_case(...)

.. admonition:: Important
   :class: danger

   Mirroring and custom coordinate systems are available only with Geometry AI enabled.

.. seealso::

  - :doc:`Windsor body with Geometry AI <../example_library/notebooks/windsor_body>`