Skip to content

Commit c664d6d

Browse files
TesshubTesshub
committed
đź“ť update simulation_options documentation and handling of 'x' parameter and tutorial
1 parent 77cd50b commit c664d6d

2 files changed

Lines changed: 87 additions & 95 deletions

File tree

‎modelitool/simulate.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -81,14 +81,16 @@ def simulate(
8181
) -> pd.DataFrame:
8282
"""
8383
Runs the simulation with the provided parameters, simulation options and
84-
boundariy conditions.
84+
boundary conditions.
8585
- parameter_dict (dict, optional): Dictionary of parameters.
86-
- simulation_options (dict, optional): Will update simulation options if it
87-
had been given at the init phase. May include values for "startTime",
88-
"stopTime", "stepSize", "tolerance", "solver", "outputFormat".
86+
- simulation_options (dict, optional): May include values for "startTime",
87+
"stopTime", "stepSize", "tolerance", "solver", "outputFormat". Can
88+
also include 'x' with a DataFrame for boundary conditions.
8989
- x (pd.DataFrame, optional): Input data for the simulation. Index shall
90-
be a DatetimeIndex or integers. Columns must match the combi time table
91-
used to specify boundary conditions in the Modelica System.
90+
be a DatetimeIndex or integers. Columns must match the combitimetable
91+
used to specify boundary conditions in the Modelica System. If 'x' is
92+
provided both in simulation_options and as a direct parameter, the one
93+
provided as direct parameter will be used.
9294
- verbose (bool, optional): If True, prints simulation progress. Defaults to
9395
True.
9496
- simflags (str, optional): Additional simulation flags.
@@ -185,12 +187,10 @@ def _set_simulation_options(self, simulation_options):
185187
'outputFormat': simulation_options.get('outputFormat')
186188
}
187189

188-
# Filtrer les options None
189190
options = [f'{k}={v}' for k, v in standard_options.items() if v is not None]
190191
self.model.setSimulationOptions(options)
191192
self.simulation_options = simulation_options
192193

193-
# Gérer x s'il est présent dans les options
194194
if 'x' in simulation_options:
195195
self._set_x(simulation_options['x'])
196196

‎tutorials/Modelica models Handling.ipynb‎

Lines changed: 79 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@
7777
"source": [
7878
"# 2. Set boundary file\n",
7979
"## Option A: load csv file\n",
80-
"Let's load measurement data on python. We can use this dataframe directly in our simulator class to define boundary conditions."
80+
"Let's load measurement data on python. We can use this dataframe to define boundary conditions of our model."
8181
]
8282
},
8383
{
@@ -151,133 +151,139 @@
151151
},
152152
{
153153
"cell_type": "markdown",
154-
"id": "f2dedef9-dc04-430f-8fe8-754c39ab7105",
155-
"metadata": {},
156-
"source": [
157-
"#### Set up simulation options \n",
158-
"\n",
159-
"Before loading the modelica file, we need to specify the simulation running options. In Modelica, <code>startTime</code> and <code>stopTime</code> correspond to the number\n",
160-
"of seconds since the beginning of the year. \n",
161-
"\n",
162-
"The values can be found in the file created earlier using <code>df_to_combitimetable</code> . Another way is to use the index of the <code>DataFrame</code> we just created.\n",
163-
"The modelitool function <code>modelitool.combitabconvert.datetime_to_seconds</code>\n",
164-
"helps you convert datetime index in seconds.\n"
165-
]
166-
},
167-
{
168-
"cell_type": "code",
169-
"execution_count": null,
170-
"id": "b26a8f6e-2f1a-41ed-a74e-dc9a41435110",
154+
"id": "0ea8c4b4-2eab-429c-a67d-743aaa47a5bd",
171155
"metadata": {},
172-
"outputs": [],
173156
"source": [
174-
"from modelitool.combitabconvert import datetime_to_seconds"
157+
"To avoid loading all ouptut from modelica model, let's first define a list of output that will be included in the dataframe output for any simulation."
175158
]
176159
},
177160
{
178161
"cell_type": "code",
179162
"execution_count": null,
180-
"id": "a7472557-a5af-49bf-8ffc-08f30741e4c9",
163+
"id": "64149508-369a-4a8c-8928-6c71090b4428",
181164
"metadata": {},
182165
"outputs": [],
183166
"source": [
184-
"simulation_df = reference_df.loc[\"2018-03-22\":\"2018-03-23\"]\n",
185-
"second_index = datetime_to_seconds(simulation_df.index)"
167+
"output_list = [\n",
168+
" \"T_coat_ins.T\",\n",
169+
" \"T_ins_ins.T\",\n",
170+
" \"Tw_out.T\"\n",
171+
"]"
186172
]
187173
},
188174
{
189175
"cell_type": "markdown",
190-
"id": "d4d76fff-d5c5-45b3-805b-255ee67e6ddc",
176+
"id": "b092bb4236cc85f3",
191177
"metadata": {},
192178
"source": [
193-
"- <code>stepSize</code> is the simulation timestep size. In this case it's 5 min or\n",
194-
"300 sec.\n",
195-
"- <code>tolerance</code> and <code>solver</code> are related to solver configuration\n",
196-
"do not change if you don't need to.\n",
197-
"- <code>outputFormat</code> can be either csv or mat. csv will enable faster data handling during sensitivity analyses and optimizations."
179+
"Now, we can load the *om file.\n",
180+
"\n",
181+
"The `OMModel` class is used to load and simulate Modelica models. It requires the following parameters:\n",
182+
"\n",
183+
"- `model_path`: Path to the Modelica model file (*.mo) or model name if already loaded in OpenModelica\n",
184+
"- `package_path` (optional): Path to additional Modelica packages required by the model\n",
185+
"- `simulation_options` (optional): Dictionary containing simulation settings like:\n",
186+
" - `startTime`: Start time in seconds\n",
187+
" - `stopTime`: Stop time in seconds\n",
188+
" - `stepSize`: Time step for the simulation\n",
189+
" - `tolerance`: Numerical tolerance for the solver\n",
190+
" - `solver`: Solver to use (e.g. \"dassl\")\n",
191+
" - `outputFormat`: \"mat\" or \"csv\" for results format\n",
192+
" - `x`: Boundary conditions as a DataFrame (optional)\n",
193+
"- `output_list` (optional): List of variables to include in simulation results\n",
194+
"- `lmodel` (optional): List of required Modelica libraries (e.g. [\"Modelica\"])"
198195
]
199196
},
200197
{
201198
"cell_type": "code",
202199
"execution_count": null,
203-
"id": "4cbdd9d0-c377-484f-a4bd-d73fe3e741e2",
200+
"id": "3264057e-66ef-41c6-b75a-6efd28748f8c",
204201
"metadata": {},
205202
"outputs": [],
206203
"source": [
207-
"simulation_df"
204+
"from modelitool.simulate import OMModel"
208205
]
209206
},
210207
{
211208
"cell_type": "code",
212209
"execution_count": null,
213-
"id": "604aa9ed-b37b-4e61-b96e-a6dfdad42ca7",
210+
"id": "8d9bfb90-3f07-49e9-9d7f-314ec3a07fc1",
214211
"metadata": {},
215212
"outputs": [],
216213
"source": [
217-
"simulation_opt = {\n",
218-
" \"startTime\": second_index[0],\n",
219-
" \"stopTime\": second_index[-1],\n",
220-
" \"stepSize\": 300,\n",
221-
" \"tolerance\": 1e-06,\n",
222-
" \"solver\": \"dassl\",\n",
223-
" \"outputFormat\": \"csv\"\n",
224-
"}"
214+
"simu_OM = OMModel(\n",
215+
" model_path=Path(TUTORIAL_DIR) / \"resources/etics_v0.mo\",\n",
216+
" output_list=output_list,\n",
217+
" lmodel=[\"Modelica\"],\n",
218+
")"
225219
]
226220
},
227221
{
228222
"cell_type": "markdown",
229-
"id": "0ea8c4b4-2eab-429c-a67d-743aaa47a5bd",
223+
"id": "766241a0-95b8-4916-9206-1ca240b2f361",
230224
"metadata": {},
231225
"source": [
232-
"Finally, we can define a list of output that will be included in the dataframe output for any simulation."
226+
"#### Set up simulation options \n",
227+
"\n",
228+
"As they were not specified when instantiating OMModel, simulation running options (if different from the one provided by the modelica model) should be defined.\n",
229+
"\n",
230+
"In Modelica, <code>startTime</code> and <code>stopTime</code> correspond to the number\n",
231+
"of seconds since the beginning of the year. \n",
232+
"\n",
233+
"The values can be found in the file created earlier using <code>df_to_combitimetable</code> . Another way is to use the index of the <code>DataFrame</code> we just created.\n",
234+
"The modelitool function <code>modelitool.combitabconvert.datetime_to_seconds</code>\n",
235+
"helps you convert datetime index in seconds.\n"
233236
]
234237
},
235238
{
236239
"cell_type": "code",
237240
"execution_count": null,
238-
"id": "64149508-369a-4a8c-8928-6c71090b4428",
241+
"id": "b26a8f6e-2f1a-41ed-a74e-dc9a41435110",
239242
"metadata": {},
240243
"outputs": [],
241244
"source": [
242-
"output_list = [\n",
243-
" \"T_coat_ins.T\",\n",
244-
" \"T_ins_ins.T\",\n",
245-
" \"Tw_out.T\"\n",
246-
"]"
245+
"from modelitool.combitabconvert import datetime_to_seconds"
247246
]
248247
},
249248
{
250-
"cell_type": "markdown",
251-
"id": "b092bb4236cc85f3",
249+
"cell_type": "code",
250+
"execution_count": null,
251+
"id": "a7472557-a5af-49bf-8ffc-08f30741e4c9",
252252
"metadata": {},
253+
"outputs": [],
253254
"source": [
254-
"Now let's load the *om file: \n"
255+
"simulation_df = reference_df.loc[\"2018-03-22\":\"2018-03-23\"]\n",
256+
"second_index = datetime_to_seconds(simulation_df.index)"
255257
]
256258
},
257259
{
258-
"cell_type": "code",
259-
"execution_count": null,
260-
"id": "3264057e-66ef-41c6-b75a-6efd28748f8c",
260+
"cell_type": "markdown",
261+
"id": "9d771fd7-bdde-4b90-9d3e-699d3f488099",
261262
"metadata": {},
262-
"outputs": [],
263263
"source": [
264-
"from modelitool.simulate import OMModel"
264+
"- <code>stepSize</code> is the simulation timestep size. In this case it's 5 min or\n",
265+
"300 sec.\n",
266+
"- <code>tolerance</code> and <code>solver</code> are related to solver configuration\n",
267+
"do not change if you don't need to.\n",
268+
"- <code>outputFormat</code> can be either csv or mat. csv will enable faster data handling during sensitivity analyses and optimizations.\n",
269+
"- <code>x</code>: as the boundary conditions. If not given here, it can still be provided in method `simulate`."
265270
]
266271
},
267272
{
268273
"cell_type": "code",
269274
"execution_count": null,
270-
"id": "8d9bfb90-3f07-49e9-9d7f-314ec3a07fc1",
275+
"id": "604aa9ed-b37b-4e61-b96e-a6dfdad42ca7",
271276
"metadata": {},
272277
"outputs": [],
273278
"source": [
274-
"simu_OM = OMModel(\n",
275-
" model_path=Path(TUTORIAL_DIR) / \"resources/etics_v0.mo\",\n",
276-
" simulation_options=simulation_opt,\n",
277-
" x=simulation_df,\n",
278-
" output_list=output_list,\n",
279-
" lmodel=[\"Modelica\"],\n",
280-
")"
279+
"simulation_opt = {\n",
280+
" \"startTime\": second_index[0],\n",
281+
" \"stopTime\": second_index[-1],\n",
282+
" \"stepSize\": 300,\n",
283+
" \"tolerance\": 1e-06,\n",
284+
" \"solver\": \"dassl\",\n",
285+
" \"outputFormat\": \"csv\"\n",
286+
"}"
281287
]
282288
},
283289
{
@@ -293,7 +299,7 @@
293299
"id": "02e59be3-e4f4-44f0-adcd-66a43d200146",
294300
"metadata": {},
295301
"source": [
296-
"Set the initial and parameter values in a dictionary."
302+
"Set the initial and parameter values in a dictionary. They can either be set before simluation (with `set_param_dict()` method, or when using method `simulate()`. Each change of paramter value overwrite the previous one. "
297303
]
298304
},
299305
{
@@ -317,12 +323,14 @@
317323
"id": "65fd55a9-959f-4bef-9ee2-14d0c617b75b",
318324
"metadata": {},
319325
"source": [
320-
"Simulation flags can be specified in <code>simulate()</code> method. Overview of possible simulation flags can be found here: https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/simulationflags.html. Note that the simulation flag <code>override</code> cannot be used, as it was already used in class <code>OMModel</code> with <code>simulation_options</code>.\n",
326+
"Simulation flags can also be specified in <code>simulate()</code> method. Overview of possible simulation flags can be found here: https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/simulationflags.html. Note that the simulation flag <code>override</code> cannot be used, as it was already used in class <code>OMModel</code> with <code>simulation_options</code>.\n",
321327
"\n",
322-
"If x boundary conditions is not specified or do not\n",
328+
"If x boundary conditions do not\n",
323329
" have a DateTime index (seconds int), a year can be specified to convert\n",
324330
" int seconds index to a datetime index. If simulation spans overs several\n",
325-
" years, it shall be the year when it begins."
331+
" years, it shall be the year when it begins.\n",
332+
"\n",
333+
"The output of the `simulate()` method is a dataframe, containing the outputs listed in output_list."
326334
]
327335
},
328336
{
@@ -335,26 +343,10 @@
335343
"init_res_OM = simu_OM.simulate(\n",
336344
" simflags = \"-initialStepSize=60 -maxStepSize=3600 -w -lv=LOG_STATS\",\n",
337345
" parameter_dict=parameter_dict_OM,\n",
346+
" x=reference_df,\n",
338347
" year=2024,\n",
339-
")"
340-
]
341-
},
342-
{
343-
"cell_type": "markdown",
344-
"id": "70cfed9f-467b-44b2-b80d-459dc02288ae",
345-
"metadata": {},
346-
"source": [
347-
"Results are displayed in a dataframe:"
348-
]
349-
},
350-
{
351-
"cell_type": "code",
352-
"execution_count": null,
353-
"id": "4820b4f3-c446-4f65-869b-aee86ac96806",
354-
"metadata": {},
355-
"outputs": [],
356-
"source": [
357-
"init_res_OM"
348+
")\n",
349+
"init_res_OM.head()"
358350
]
359351
},
360352
{

0 commit comments

Comments
 (0)