Add content in geometry page

Author: ggiraldof

tutorial/geometry_upload_and_import.rst

@@ -1,9 +1,185 @@
 Geometry Upload and Import
 ==========================
 
-To Do:
+All simulations in the SimScale platform are built on top of a geometry model, and physics concepts
+such as material models, boundary conditions and interactions are assigned to geometrical features
+such as volumes and faces. 
 
-* Explanation of the geometry import process
-* How to create an storage
-* How to upload a geometry
-* How to import a geometry to the project
+The geometrical model is defined via a CAD file. Some of the CAD formats supported in the platform
+include:
+
+* Parasolid
+* Solidworks
+* Inventor
+* Rinho
+* CATIA
+* ACIS
+* STEP
+* IGES
+* STL
+
+For a CAD geometry to be available for simulation use via the SDK, a two-step process
+is performed:
+
+1. Upload the CAD file to the platform storage
+2. Import the stored file into the project
+
+After the geometry is imported to the project, it can be used to build a simulation on top of it.
+
+
+Uploading the CAD File
+----------------------
+
+In order to upload a CAD file to the platform, a ``storage`` is first created, by making use of
+the ``StorageApi`` module:
+
+
+.. code-block:: python
+
+    import simscale_sdk as sim
+
+    storage_api = sim.StorageApi(api_client)
+
+    storage = storage_api.create_storage()
+
+
+Then we can read the CAD file stored locally and upload it with a ``PUT`` request. The ``URL``
+for the request is available in the ``storage`` object:
+
+
+.. code-block:: python
+
+    with open("cad_file.x_t", "rb") as file:
+        
+        api_client.rest_client.PUT(
+            url=storage.url,
+            headers={
+                "Content-Type": "application/octet-stream"
+            },
+            body=file.read()
+        )
+
+
+After the request is completed, the file is stored in SimScale's cloud and is ready to
+be imported into a simulation project. For instance, the storage is identified by an ``UUID``:
+
+
+.. code-block:: python
+
+    storage_id = storage.storage_id
+
+    print(f"{storage_id=}")
+
+
+Importing the Geometry into the Project
+---------------------------------------
+
+In order to deal with geometry data and the related operations, the SDK offers the 
+``GeometryImportRequest`` object and the ``GeometryImportsApi`` module. We first define the 
+relevant data for the CAD file, because the platform still doesn't know about the format, 
+name, import options, etc., then use the ``GeometryImportsApi.import_geometry`` function:
+
+
+.. code-block:: python
+
+    import simscale_sdk as sim
+
+    geometry_import_api = sim.GeometryImportsApi(api_client)
+
+    geometry_import_req = sim.GeometryImportRequest(
+        name="Geometry 1",
+        location=sim.GeometryImportRequestLocation(storage_id),
+        format="PARASOLID",
+        input_unit="m",
+        options=sim.GeometryImportRequestOptions(
+            facet_split=False,
+            sewing=False,
+            improve=True,
+            optimize_for_lbm_solver=False
+        ),
+    )
+
+    geometry_import = geometry_import_api.import_geometry(project_id, geometry_import_req)
+
+    geometry_import_id = geometry_import.geometry_import_id
+
+
+The ``GeometryImportsApi.import_geometry`` method takes some time to complete its work, and is a 
+non-blocking call, because the action happens in the platform. In order to sync our code 
+with the execution of the task, we create a loop to check the status of the operation at a given
+frequency.
+
+
+.. code-block:: python
+
+    import time
+
+    while geometry_import.status not in ("FINISHED", "CANCELED", "FAILED"):
+
+        geometry_import = geometry_import_api.get_geometry_import(project_id, geometry_import_id)
+
+        time.sleep(10)
+
+
+An improved version of this snippet also adds a time-out check:
+
+
+.. code-block:: python
+
+    import time
+
+    GEOMETRY_IMPORT_TIMEOUT = 900
+
+    import_start = time.time()
+
+    while geometry_import.status not in ("FINISHED", "CANCELED", "FAILED"):
+
+        if time.time() > import_start + GEOMETRY_IMPORT_TIMEOUT:
+            raise TimeoutError()
+
+        geometry_import = geometry_import_api.get_geometry_import(project_id, geometry_import_id)
+
+        time.sleep(10)
+
+
+Then we can process the result of the operation, such as getting the id for the imported geometry:
+
+
+.. code-block:: python
+
+    if geometry_import.status != "FINISHED":
+        raise Error("Geometry import operation was canceled or failed.")
+
+    geometry_id = geometry_import.geometry_id
+
+    print(f"{geometry_id=}")
+
+
+This is a common pattern that we will encounter on non-blocking operations that are launched 
+with the API, but that we need to sync with because the results are to be used in suqsequent 
+operations. Such cases would include mesh computation, simulation run execution, etc.
+
+Also, this loop is a great opportunity for an async execution break point. If you are running 
+multiple such operations in a parallel asyncio loop, instead of waiting 10 seconds on a blocking 
+call, you can mark the hypervisor to switch tasks at this point. For instance, take a look at the 
+following snippet:
+
+
+.. code-block:: python
+
+    import asyncio
+
+    async def async_import_geometry(geoemetry_import_req, project_id):
+
+        # Do the preparation tasks and launch the import
+
+        while geometry_import.status not in ("FINISHED", "CANCELED", "FAILED"):
+
+            if time.time() > import_start + GEOMETRY_IMPORT_TIMEOUT:
+                raise TimeoutError()
+
+            geometry_import = geometry_import_api.get_geometry_import(project_id, geometry_import_id)
+
+            await asyncio.sleep(10)
+
+        return geometry_import.geometry_id