Skip to content

Commit 408e412

Browse files
ggiraldofggiraldof
committed
Add content to simulation setup page
1 parent d78b205 commit 408e412

File tree

1 file changed

+272
-6
lines changed

1 file changed

+272
-6
lines changed

‎tutorial/simulation_setup.rst

+272-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,276 @@
11
Simulation Setup
22
================
33

4-
To Do:
4+
Having the geometry model already available in the project, the next step to
5+
setup a simulation is to specify the physcis model. This is performed via a simulation
6+
``Spec`` (short for specification), an object that contains the following data:
57

6-
* Introduction to the minimum and optional data for a simulation
7-
* How to create a material and assign from scratch
8-
* How to create a material from the library
9-
* How to create a boundary condition
10-
* Introduce to usage of the Swagger documentation
8+
* Name of the simulation
9+
* Geometry ID
10+
* Physical model
11+
12+
A ``SimulationSpec`` object is initialized with this data, then passed to the
13+
``SimulationsApi.create_simulation()`` method:
14+
15+
16+
.. code-block:: python
17+
18+
import simscale_sdk as sim
19+
20+
simulations_api = sim.SimulationsApi(api_client)
21+
22+
simulation_spec = sim.SimulationSpec(
23+
name="Incompressible",
24+
geometry_id=geometry_id,
25+
model=model
26+
)
27+
28+
simulation = simulation_api.create_simulation(project_id, simulation_spec)
29+
30+
31+
Now we need to dwelve deeper into the physics ``model``.
32+
33+
Model
34+
-----
35+
36+
The ``model`` object completely defines the characteristics and physical conditions
37+
of the system to be simulated, alongside the numerics properties and simulation control.
38+
For instance, the following data is captured in the model:
39+
40+
* Materials models
41+
* Initial conditions
42+
* Boundary conditions
43+
* Interactions between multiple components
44+
* Numerical methods and parameters
45+
* Simulated time and time stepping
46+
* Computed output fields and derived data
47+
48+
Notice that this is a rather long amount of data, and as such it will be broken
49+
part by part. Also, not all of this data is required to setup a simulation, and
50+
the specifics will depend on the particular physics of the model.
51+
52+
For the sake of this tutorial, we will cover an ``Incompressible`` model as
53+
an exampl:
54+
55+
.. code-block:: python
56+
57+
import simscale_sdk as sim
58+
59+
tutorial_model = sim.Incompressible(
60+
model=sim.FluidModel(),
61+
initial_conditions=sim.FluidInitialConditions(),
62+
advanced_concepts=sim.AdvancedConcepts(),
63+
materials=sim.IncompressibleFluidMaterials(
64+
...
65+
),
66+
numerics=sim.FluidNumerics(
67+
relaxation_factors=sim.RelaxationFactor(),
68+
pressure_reference_vale=sim.DimensionalPressure(value=0, unit="Pa"),
69+
residual_controls=sim.ResidualControls(
70+
velocity=sim.Tolerance(),
71+
pressure=sim.Tolerance(),
72+
turbulent_kinetic_energy=sim.Tolerance(),
73+
omega_dissipation_rate=sim.Tolerance(),
74+
),
75+
solvers=sim.FluidSolvers(),
76+
schemes=sim.Schemes(
77+
time_differentiation=sim.TimeDifferentiationSchemes(),
78+
gradient=sim.GradientSchemes(),
79+
divergence=sim.DivergenceSchemes(),
80+
laplacian=sim.LaplacianSchemes(),
81+
interpolation=sim.InterpolationSchemes(),
82+
surface_normal_gradient=sim.SurfaceNormalGradientSchemes(),
83+
),
84+
),
85+
boundary_conditions=[
86+
...
87+
],
88+
simulation_control=sim.FluidSimulationControl(
89+
end_time=sim.DimensionalTime(value=100, unit="s"),
90+
delta_t=sim.DimensionalTime(value=1, unit="s"),
91+
write_control=sim.TimeStepWriteControl(write_interval=20),
92+
max_run_time=sim.DimensionalTime(value=10000, unit="s"),
93+
decompose_altorithm=sim.ScotchDecomposeAlgorithm(),
94+
)
95+
result_control=sim.FluidResultControls()
96+
)
97+
98+
99+
In this example we used mostly the default values for each object parameter. Of course,
100+
each one of these objects has its own parameters to finely tune the behavior of the
101+
simulation. If you need to look at the detail of each object and its parameters, please
102+
check the SDK documentation:
103+
104+
`Python SDK Documentation <https://simscalegmbh.github.io/simscale-python-sdk/simscale_sdk.api.html>`
105+
106+
We will focus, as an example, on the most basic setup for a fluid simulation: the material
107+
model and the boundary conditions.
108+
109+
Material Model
110+
--------------
111+
112+
Being a single fluid phase simulation, there is only one material that we need to setup.
113+
Following we will enter the properties for water at ambient temperature, and assign it
114+
to the only volumetric region in the geometry:
115+
116+
.. code-block:: python
117+
118+
materials=sim.IncompressibleFluidMaterials(
119+
fluids=[
120+
sim.IncompressibleMaterial(
121+
name="Water",
122+
type="INCOMPRESSIBLE",
123+
viscosity_model=sim.NewtonianViscosityModel(
124+
type="NEWTONIAN",
125+
kinematic_viscosity=sim.DimensionalKinematicViscosity(
126+
value=9.3379E-7,
127+
unit="m²/s",
128+
),
129+
),
130+
density=sim.DimensionalDensity(
131+
value=997.33,
132+
unit="kg/m³",
133+
),
134+
topological_reference=sim.TopologicalReference(
135+
entities=[
136+
"B1_TE39",
137+
],
138+
sets=[],
139+
),
140+
),
141+
],
142+
),
143+
144+
145+
Boundary conditions
146+
-------------------
147+
148+
In this simulation we need three boundary conditions:
149+
150+
1. Velocity inlet 1, at 1.5 m/s
151+
2. Velocity inlet 2, at 1 m/s
152+
3. Pressure outlet, at 0 Pa
153+
154+
The boundary conditions are setup with the following code:
155+
156+
.. code-block:: python
157+
158+
boundary_conditions=[
159+
sim.VelocityInletBC(
160+
name="Velocity inlet 1",
161+
velocity=sim.FixedValueVBC(
162+
value=sim.DimensionalVectorFunctionSpeed(
163+
value=sim.ComponentVectorFunction(
164+
x=sim.ConstantFunction(
165+
value=0,
166+
),
167+
y=sim.ConstantFunction(
168+
value=0,
169+
),
170+
z=sim.ConstantFunction(
171+
value=-1.5,
172+
),
173+
),
174+
unit="m/s",
175+
),
176+
),
177+
topological_reference=sim.TopologicalReference(
178+
entities=[
179+
"B1_TE3",
180+
],
181+
),
182+
),
183+
VelocityInletBC(
184+
name="Velocity inlet 2",
185+
velocity=sim.FixedValueVBC(
186+
value=sim.DimensionalVectorFunctionSpeed(
187+
value=sim.ComponentVectorFunction(
188+
x=sim.ConstantFunction(
189+
value=0,
190+
),
191+
y=sim.ConstantFunction(
192+
value=-1,
193+
),
194+
z=sim.ConstantFunction(
195+
value=0,
196+
),
197+
),
198+
unit="m/s",
199+
),
200+
),
201+
topological_reference=sim.TopologicalReference(
202+
entities=[
203+
"B1_TE30",
204+
],
205+
),
206+
),
207+
PressureOutletBC(
208+
name="Pressure outlet",
209+
gauge_pressure=sim.FixedValuePBC(
210+
value=sim.DimensionalFunctionPressure(
211+
value=sim.ConstantFunction(
212+
value=0,
213+
),
214+
unit="Pa",
215+
),
216+
),
217+
topological_reference=sim.TopologicalReference(
218+
entities=[
219+
"B1_TE37",
220+
],
221+
),
222+
),
223+
],
224+
225+
226+
Generating SDK Code
227+
-------------------
228+
229+
It might be difficult to navigate the documentation and reference pages to create a
230+
simulation spec from scratch. Some of the reasons would be:
231+
232+
* How to find out the internal entity name for my part or face?
233+
* How to know for sure the appropriate objects for the parameters?
234+
* How to know the units?
235+
236+
An alternative route to get there is to setup the simulation in the Workbench,
237+
then use the automatic code generator provided by the SDK. For this you need
238+
the project id and the simulation id. You can obtain the project id from the
239+
workbench URL, looking for the ``pid=`` parameter. Then you can query the project
240+
for the available simulations. For example:
241+
242+
243+
.. code-block:: python
244+
245+
print(simulations_api.get_simulations(project_id))
246+
247+
248+
Will print something like the following:
249+
250+
251+
.. code-block:: python
252+
253+
{'embedded': [{'name': 'Incompressible',
254+
'simulation_id': '326cf56d-d72c-4672-8686-45f46e229792'}],
255+
'links': {'_self': {'href': '/projects/1562209390575198452/simulations?page=1&limit=100'},
256+
'first': {'href': '/projects/1562209390575198452/simulations?page=1&limit=100'},
257+
'last': {'href': '/projects/1562209390575198452/simulations?page=1&limit=100'},
258+
'next': {'href': '/projects/1562209390575198452/simulations?page=1&limit=100'},
259+
'prev': {'href': '/projects/1562209390575198452/simulations?page=1&limit=100'}},
260+
'meta': {'total': 1}}
261+
262+
263+
We can identify that we want the simulation named 'Incompressible', and copy its ``simulation_id``.
264+
265+
Now, to generate the SDK code for this simulation model, we can do as follows:
266+
267+
268+
.. code-block:: python
269+
270+
sdk_code = simulations_api.get_simulation_sdk_code(project_id, simulation_id)
271+
272+
with open("sim_code.py", "w") as f:
273+
f.write(str(sdk_code))
274+
275+
276+
Then all of the simulation spec will be found in the ``sim_code.py`` file.

0 commit comments

Comments
 (0)