add tutorial import STL file

docs/pages/user_guide.rst

@@ -8,6 +8,7 @@ User Guide \& How-To's
     :glob:
 
     user_guide/restart_simu.rst
+    user_guide/import_stl.rst
     user_guide/developer_guidance.rst
     user_guide/parameters.rst
     user_guide/list_files.rst

docs/pages/user_guide/import_stl.rst

@@ -0,0 +1,49 @@
+How to import an STL file and run a simulation with an immersed body
+====================================================================
+
+**This tutorial is designed for an Ubuntu workstation for the simulation around a sphere**
+
+Install the xcompact3d toolbox
+------------------------------
+
+First you need to make sure to have ``conda`` installed on your machine. See for instance `here <https://linuxconfig.org/installing-anaconda-on-ubuntu-24-04>`_ for an installation on Ubuntu.
+
+.. code-block::
+
+	conda create -n x3d python=3.XX
+	conda activate x3d
+	pip install xcompact3d-toolbox
+
+Install and compile Xcompact3d
+------------------------------
+
+.. code-block::
+
+	git clone https://github.com/xcompact3d/Incompact3d.git
+	cd Incompact3d/
+	export FC=mpif90
+	cmake -S . -B build
+	cd build/
+	cmake --build . -j 8
+
+The executable file is in the ``build/bin`` directory
+
+Bug fix in the xcompact3d_toolbox package
+-----------------------------------------
+
+open ``/home/username/anaconda3/envs/x3d/lib/python3.12/site-packages/xcompact3d_toolbox/sandbox.py`` and change all instances of longdouble to double (lines 438-441)
+
+Generate the initial conditions including the epsilon function
+--------------------------------------------------------------
+.. code-block::
+
+	cd examples/case_sphere
+	python3 generate_initial_conditions.py
+	
+Run the simulation on 8 cores (~7minutes)
+-----------------------------------------
+.. code-block::
+	
+	mpirun -np 8 ../../build/bin/xcompact3d
+
+

examples/Sphere/README

@@ -0,0 +1 @@
+please have a look at the Xcompact3d readthedocs website for how to import an STL file and run the simulation for the flow around a sphere.

examples/Sphere/generate_initial_conditions.py

@@ -0,0 +1,45 @@
+# Import necessary libraries
+import xcompact3d_toolbox as x3d
+import numpy as np
+import xarray as xr
+import math
+
+# Initialise parameters
+x3d.param["mytype"] = np.float64
+
+# Load parameters
+prm  = x3d.Parameters(loadfile='input.i3d')
+epsi = x3d.init_epsi(prm, dask=True)
+
+# Read the STL file
+for key in epsi.keys():
+    print(key)
+    epsi[key] = epsi[key].geo.from_stl("sphere.stl",
+                                       origin=dict(x=2.0,y=2.0,z=2.0), # locates the sphere centre at (2.5, 2.5, 2.5)
+                                       scale=1.0/200.0, # Sphere has a diameter of 200, so rescale to a diameter of 1
+                                       # rotate=dict(axis=[0,0,1],theta=math.radians(270)), # rotate the geometry
+                                       user_tol=1e-3)
+dataset = x3d.gene_epsi_3D(epsi, prm)
+
+if prm.iibm >= 2:
+    prm.nobjmax = dataset.obj.size
+    print(prm.nobjmax) # If using iibm = 2, set nobjmax in input.i3d to the value of this print
+
+ds  = x3d.init_dataset(prm)
+
+# Set boundary conditions
+for key in 'bxx1 bxy1 bxz1'.split():
+    print(ds[key].attrs['name'])
+    ds[key] *= 0.0
+    if key=='bxx1':
+        ds[key] += 1.0
+
+# Set initial conditions
+for key in 'ux uy uz'.split():
+    print(ds[key].attrs['name'])
+    ds[key] *= 0.0
+    if key=='ux':
+        ds[key] += 1.0
+
+# Write the fields
+prm.dataset.write(ds)

examples/Sphere/input.i3d

@@ -0,0 +1,135 @@
+! -*- mode: f90 -*-
+
+!===================
+&BasicParam
+!===================
+
+       C_filter = 0.49            ! 
+           beta = 1.0             ! Refinement parameter
+             dt = 2.0e-3          ! Time step
+          gravx = 0.0             ! Gravity unitary vector in x-direction
+          gravy = 0.0             ! Gravity unitary vector in y-direction
+          gravz = 0.0             ! Gravity unitary vector in z-direction
+        ifilter = 0               ! 
+         ifirst = 1               ! The number for the first iteration
+           iibm = 2               ! Flag for immersed boundary method (0: No, 1: Yes)
+            iin = 1               ! Defines perturbation at initial condition
+          ilast = 10000           ! The number for the last iteration
+        ilesmod = 0               ! Enables Large-Eddy methodologies (0: No, 1: Yes)
+           ilmn = .false.          ! 
+   inflow_noise = 0.0             ! Turbulence intensity (1=100%) !! Inflow condition
+     init_noise = 0.0             ! Turbulence intensity (1=100%) !! Initial condition
+          ipost = 0               ! Enables online postprocessing at a frequency iprocessing (0: No, 1: Yes)
+        iscalar = 0               ! 
+         istret = 0               ! y mesh refinement (0:no, 1:center, 2:both sides, 3:bottom)
+       iturbine = 0               ! 
+          itype = 12              ! Flow configuration (1:Lock-exchange, 2:TGV, 3:Channel, and others)
+          ivisu = 1               ! Enable store snapshots at a frequency ioutput (0: No, 1: Yes)
+          nclx1 = 2               ! Velocity boundary condition where x=0
+          nclxn = 2               ! Velocity boundary condition where x=xlx
+          ncly1 = 0               ! Velocity boundary condition where y=0
+          nclyn = 0               ! Velocity boundary condition where y=yly
+          nclz1 = 0               ! Velocity boundary condition where z=0
+          nclzn = 0               ! Velocity boundary condition where z=zlz
+      numscalar = 0               ! Number of scalar fractions
+             nx = 129             ! X-direction nodes
+             ny = 64             ! Y-direction nodes
+             nz = 64             ! Z-direction nodes
+          p_col = 0               ! Column partition for domain decomposition and parallel computation
+          p_row = 0               ! Row partition for domain decomposition and parallel computation
+             re = 1000.0           ! Reynolds number
+             u1 = 1.0             ! 
+             u2 = 1.0             ! 
+            xlx = 10.0             ! Size of the box in x-direction
+            yly = 5.0             ! Size of the box in y-direction
+            zlz = 5.0             ! Size of the box in z-direction
+
+/End
+
+!===================
+&NumOptions
+!===================
+
+            cnu = 0.44            ! Ratio between hyperviscosity at km=2/3π and kc=π (dissipation factor range)
+      ifirstder = 4               ! 
+      iimplicit = 0               ! 
+     isecondder = 4               ! Scheme for second order derivative
+    itimescheme = 3               ! Time integration scheme (1: Euler, 2: AB2, 3: AB3, 5: RK3)
+          nu0nu = 0.0             ! Ratio between hyperviscosity/viscosity at nu (dissipation factor intensity)
+        ipinter = 2               ! interpolation scheme (1: classic, 2: optimized, 3: optimized agressive)
+
+
+/End
+
+!===================
+&InOutParam
+!===================
+
+    icheckpoint = 100            ! Frequency for writing backup file
+       ioutflow = 0               ! 
+        ioutput = 100             ! Frequency for visualization file
+          !ilist = 1
+    iprocessing = 100            ! Frequency for online postprocessing
+       irestart = 0               ! Read initial flow field (0: No, 1: Yes)
+       ninflows = 1               ! 
+        nprobes = 0               ! 
+     ntimesteps = 1               ! 
+          nvisu = 1               ! Size for visualization collection
+       output2D = 0               ! 
+
+/End
+
+!===================
+&Statistics
+!===================
+
+
+/End
+
+!===================
+&CASE
+!===================
+
+
+/End
+
+!===================
+&ScalarParam
+!===================
+
+           Tref = 0.0             ! 
+          cp(1) = 1.0             ! Initial concentration(s)
+         nclxS1 = 2               ! Scalar boundary condition where x=0
+         nclxSn = 2               ! Scalar boundary condition where x=xlx
+         nclyS1 = 0               ! Scalar boundary condition where y=0
+         nclySn = 0               ! Scalar boundary condition where y=yly
+         nclzS1 = 0               ! Scalar boundary condition where z=0
+         nclzSn = 0               ! Scalar boundary condition where z=zlz
+          ri(1) = 0.0             ! Richardson number(s)
+          sc(1) = 1.0             ! Schmidt number(s)
+        uset(1) = 1.0             ! Settling velocity(ies)
+
+/End
+
+!===================
+&LESModel
+!===================
+
+           jles = 1               ! LES Model (1: Phys Smag, 2: Phys WALE, 3: Phys dyn. Smag, 4: iSVV)
+        smagcst = 0.14            ! Smag damping coeff (for use with M+T damping               
+   smagwalldamp = 0               ! 0: non conservative form SGS divergence                    
+          nSmag = 0               ! WALES Model Coefficient                                    
+        walecst = 0.5             ! iconserv = 0
+
+/End
+
+!===================
+&ibmstuff
+!===================
+
+           izap = 1               ! How many points to skip for reconstruction (Range: 0-3) (Recommended: 1)
+        nobjmax = 1               ! Maximum number of objects in any direction
+           npif = 2               ! Number of Points for the Reconstruction (npif=1-3) (Recommended: 2)
+           nraf = 10              ! Level of refinement for iibm==2 to find the surface of the immersed object
+
+/End