jcmsuite-notebooks 7.4.2__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of jcmsuite-notebooks might be problematic. Click here for more details.
- jcmsuite_notebooks/__init__.py +34 -0
- jcmsuite_notebooks/_build_info.py +4 -0
- jcmsuite_notebooks/errors.py +18 -0
- jcmsuite_notebooks/generator.py +381 -0
- jcmsuite_notebooks/launcher.py +168 -0
- jcmsuite_notebooks/py.typed +0 -0
- jcmsuite_notebooks/templates/BaseTemplate.ipynb.j2 +122 -0
- jcmsuite_notebooks/templates/BaseTemplate.m +32 -0
- jcmsuite_notebooks/templates/DriverTemplate.ipynb.j2 +5 -0
- jcmsuite_notebooks/templates/DriverTemplate.m +4 -0
- jcmsuite_notebooks/templates/OptimizationTemplate.ipynb.j2 +139 -0
- jcmsuite_notebooks/templates/OptimizationTemplate.m +56 -0
- jcmsuite_notebooks/templates/ParameterScanTemplate.ipynb.j2 +100 -0
- jcmsuite_notebooks/templates/ParameterScanTemplate.m +91 -0
- jcmsuite_notebooks-7.4.2.dist-info/METADATA +74 -0
- jcmsuite_notebooks-7.4.2.dist-info/RECORD +17 -0
- jcmsuite_notebooks-7.4.2.dist-info/WHEEL +4 -0
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# SPDX-License-Identifier: MIT
|
|
2
|
+
# Copyright (c) 2001-2026 JCMwave GmbH
|
|
3
|
+
|
|
4
|
+
"""Standalone notebook and Matlab converter tooling for JCMsuite workflows."""
|
|
5
|
+
|
|
6
|
+
from .errors import (
|
|
7
|
+
NotebookConfigurationError,
|
|
8
|
+
NotebookRuntimeError,
|
|
9
|
+
NotebookToolError,
|
|
10
|
+
)
|
|
11
|
+
from .generator import (
|
|
12
|
+
NotebookLanguage,
|
|
13
|
+
NotebookTemplateKind,
|
|
14
|
+
generate_legacy_notebook_template,
|
|
15
|
+
generator_main,
|
|
16
|
+
)
|
|
17
|
+
from .launcher import (
|
|
18
|
+
is_pid_running,
|
|
19
|
+
launch_notebook_with_parent_monitor,
|
|
20
|
+
launcher_main,
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
__all__: list[str] = [
|
|
24
|
+
"NotebookConfigurationError",
|
|
25
|
+
"NotebookRuntimeError",
|
|
26
|
+
"NotebookToolError",
|
|
27
|
+
"NotebookLanguage",
|
|
28
|
+
"NotebookTemplateKind",
|
|
29
|
+
"generate_legacy_notebook_template",
|
|
30
|
+
"generator_main",
|
|
31
|
+
"is_pid_running",
|
|
32
|
+
"launch_notebook_with_parent_monitor",
|
|
33
|
+
"launcher_main",
|
|
34
|
+
]
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# SPDX-License-Identifier: MIT
|
|
2
|
+
# Copyright (c) 2001-2026 JCMwave GmbH
|
|
3
|
+
|
|
4
|
+
"""Error hierarchy for `jcmsuite_notebooks` tooling package."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class NotebookToolError(Exception):
|
|
10
|
+
"""Base exception for notebook tooling package."""
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class NotebookConfigurationError(NotebookToolError):
|
|
14
|
+
"""Raised when notebook generation/launcher input is invalid."""
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class NotebookRuntimeError(NotebookToolError):
|
|
18
|
+
"""Raised when runtime dependencies or launch environment are invalid."""
|
|
@@ -0,0 +1,381 @@
|
|
|
1
|
+
# SPDX-License-Identifier: MIT
|
|
2
|
+
# Copyright (c) 2001-2026 JCMwave GmbH
|
|
3
|
+
|
|
4
|
+
"""Jupyter/Matlab template generation for legacy notebook workflows."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import argparse
|
|
9
|
+
import json
|
|
10
|
+
import os
|
|
11
|
+
from collections.abc import Sequence
|
|
12
|
+
from dataclasses import dataclass
|
|
13
|
+
from enum import StrEnum
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import Any, cast
|
|
16
|
+
|
|
17
|
+
from .errors import NotebookConfigurationError, NotebookRuntimeError
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class NotebookLanguage(StrEnum):
|
|
21
|
+
"""Supported generated output languages."""
|
|
22
|
+
|
|
23
|
+
MATLAB = "Matlab"
|
|
24
|
+
JUPYTER_NOTEBOOK = "JupyterNotebook"
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class NotebookTemplateKind(StrEnum):
|
|
28
|
+
"""Supported workflow template families."""
|
|
29
|
+
|
|
30
|
+
DRIVER = "Driver"
|
|
31
|
+
PARAMETER_SCAN = "ParameterScan"
|
|
32
|
+
OPTIMIZATION = "Optimization"
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@dataclass(slots=True, frozen=True)
|
|
36
|
+
class MissingKeyParameter:
|
|
37
|
+
"""Normalized parameter entry loaded from legacy `MissingKeys` JSON."""
|
|
38
|
+
|
|
39
|
+
name: str
|
|
40
|
+
type: str
|
|
41
|
+
value: str | None
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
_TEMPLATE_FILE_MAP: dict[tuple[NotebookLanguage, NotebookTemplateKind], str] = {
|
|
45
|
+
(
|
|
46
|
+
NotebookLanguage.JUPYTER_NOTEBOOK,
|
|
47
|
+
NotebookTemplateKind.DRIVER,
|
|
48
|
+
): "DriverTemplate.ipynb.j2",
|
|
49
|
+
(
|
|
50
|
+
NotebookLanguage.JUPYTER_NOTEBOOK,
|
|
51
|
+
NotebookTemplateKind.PARAMETER_SCAN,
|
|
52
|
+
): "ParameterScanTemplate.ipynb.j2",
|
|
53
|
+
(
|
|
54
|
+
NotebookLanguage.JUPYTER_NOTEBOOK,
|
|
55
|
+
NotebookTemplateKind.OPTIMIZATION,
|
|
56
|
+
): "OptimizationTemplate.ipynb.j2",
|
|
57
|
+
(NotebookLanguage.MATLAB, NotebookTemplateKind.DRIVER): "DriverTemplate.m",
|
|
58
|
+
(
|
|
59
|
+
NotebookLanguage.MATLAB,
|
|
60
|
+
NotebookTemplateKind.PARAMETER_SCAN,
|
|
61
|
+
): "ParameterScanTemplate.m",
|
|
62
|
+
(
|
|
63
|
+
NotebookLanguage.MATLAB,
|
|
64
|
+
NotebookTemplateKind.OPTIMIZATION,
|
|
65
|
+
): "OptimizationTemplate.m",
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
_EXTENSION_BY_LANGUAGE: dict[NotebookLanguage, str] = {
|
|
69
|
+
NotebookLanguage.JUPYTER_NOTEBOOK: ".ipynb",
|
|
70
|
+
NotebookLanguage.MATLAB: ".m",
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def generate_legacy_notebook_template(
|
|
75
|
+
*,
|
|
76
|
+
language: NotebookLanguage | str,
|
|
77
|
+
template_kind: NotebookTemplateKind | str,
|
|
78
|
+
output_stem: str | Path,
|
|
79
|
+
project: str,
|
|
80
|
+
missing_keys_json_file: str | Path,
|
|
81
|
+
optimizer_cloud_token: str | None = None,
|
|
82
|
+
notebook_kernel_name: str = "python3",
|
|
83
|
+
) -> Path:
|
|
84
|
+
"""Generate notebook/Matlab workflow file from legacy-style template inputs.
|
|
85
|
+
|
|
86
|
+
Parameters
|
|
87
|
+
----------
|
|
88
|
+
language : NotebookLanguage | str
|
|
89
|
+
Output language selector (`"JupyterNotebook"` or `"Matlab"`).
|
|
90
|
+
template_kind : NotebookTemplateKind | str
|
|
91
|
+
Workflow family selector (`"Driver"`, `"ParameterScan"`,
|
|
92
|
+
or `"Optimization"`).
|
|
93
|
+
output_stem : str | Path
|
|
94
|
+
Output file stem without extension. The generated extension is inferred
|
|
95
|
+
from `language`.
|
|
96
|
+
project : str
|
|
97
|
+
project file name inserted into generated scripts.
|
|
98
|
+
missing_keys_json_file : str | Path
|
|
99
|
+
Path to legacy JSON file that contains a `MissingKeys` list.
|
|
100
|
+
optimizer_cloud_token : str | None, optional
|
|
101
|
+
Optional token used for explicit optimizer authentication in generated
|
|
102
|
+
optimization notebooks. When omitted, the generated notebook relies on
|
|
103
|
+
the default local/user JCMoptimizer configuration.
|
|
104
|
+
notebook_kernel_name : str, optional
|
|
105
|
+
Kernel name embedded into generated notebook metadata.
|
|
106
|
+
|
|
107
|
+
Returns
|
|
108
|
+
-------
|
|
109
|
+
Path
|
|
110
|
+
Absolute path to the generated output file.
|
|
111
|
+
|
|
112
|
+
Raises
|
|
113
|
+
------
|
|
114
|
+
NotebookConfigurationError
|
|
115
|
+
If inputs are invalid or unsupported.
|
|
116
|
+
NotebookRuntimeError
|
|
117
|
+
If Jinja2 is unavailable in the runtime environment.
|
|
118
|
+
"""
|
|
119
|
+
|
|
120
|
+
normalized_language: NotebookLanguage = _normalize_language(language)
|
|
121
|
+
normalized_kind: NotebookTemplateKind = _normalize_template_kind(template_kind)
|
|
122
|
+
|
|
123
|
+
if not notebook_kernel_name.strip():
|
|
124
|
+
raise NotebookConfigurationError("Notebook kernel name must not be empty.")
|
|
125
|
+
|
|
126
|
+
parameters: list[MissingKeyParameter] = _load_missing_keys(
|
|
127
|
+
Path(missing_keys_json_file).expanduser().resolve()
|
|
128
|
+
)
|
|
129
|
+
template_filename: str = _resolve_template_filename(
|
|
130
|
+
language=normalized_language,
|
|
131
|
+
template_kind=normalized_kind,
|
|
132
|
+
)
|
|
133
|
+
|
|
134
|
+
# `jinja2` exposes dynamic module attributes not modeled as module types.
|
|
135
|
+
# Keep `Any` scoped to this third-party boundary.
|
|
136
|
+
jinja2_module: Any = _import_jinja2()
|
|
137
|
+
template_environment: Any = jinja2_module.Environment(
|
|
138
|
+
loader=jinja2_module.PackageLoader(
|
|
139
|
+
"jcmsuite_notebooks",
|
|
140
|
+
"templates",
|
|
141
|
+
),
|
|
142
|
+
autoescape=False,
|
|
143
|
+
trim_blocks=True,
|
|
144
|
+
lstrip_blocks=True,
|
|
145
|
+
)
|
|
146
|
+
template: Any = template_environment.get_template(template_filename)
|
|
147
|
+
|
|
148
|
+
style: dict[str, str] = {
|
|
149
|
+
"user_input": "color:#a00; font-weight:bold;",
|
|
150
|
+
"optional": "color:gray",
|
|
151
|
+
}
|
|
152
|
+
if normalized_kind is NotebookTemplateKind.DRIVER:
|
|
153
|
+
style["user_input"] = ""
|
|
154
|
+
style["optional"] = ""
|
|
155
|
+
|
|
156
|
+
output_base: Path = Path(output_stem).expanduser().resolve()
|
|
157
|
+
matlab_project_parts: tuple[str, ...] = _resolve_matlab_project_parts(
|
|
158
|
+
project=project,
|
|
159
|
+
output_base=output_base,
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
rendered_text: str = cast(
|
|
163
|
+
str,
|
|
164
|
+
template.render(
|
|
165
|
+
params=parameters,
|
|
166
|
+
project=project,
|
|
167
|
+
matlab_project_parts=matlab_project_parts,
|
|
168
|
+
study_id=f"{Path(project).stem}_optimization",
|
|
169
|
+
style=style,
|
|
170
|
+
kernel_name=notebook_kernel_name,
|
|
171
|
+
optimizer_cloud_token=optimizer_cloud_token or "",
|
|
172
|
+
),
|
|
173
|
+
)
|
|
174
|
+
|
|
175
|
+
output_file: Path = output_base.with_suffix(
|
|
176
|
+
_EXTENSION_BY_LANGUAGE[normalized_language]
|
|
177
|
+
)
|
|
178
|
+
output_file.parent.mkdir(parents=True, exist_ok=True)
|
|
179
|
+
output_file.write_text(rendered_text, encoding="utf-8")
|
|
180
|
+
return output_file
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def _resolve_matlab_project_parts(
|
|
184
|
+
*, project: str, output_base: Path
|
|
185
|
+
) -> tuple[str, ...]:
|
|
186
|
+
"""Resolve project path components relative to the generated Matlab file."""
|
|
187
|
+
|
|
188
|
+
output_dir: Path = output_base.parent
|
|
189
|
+
raw_project_path: Path = Path(project)
|
|
190
|
+
project_path: Path
|
|
191
|
+
if raw_project_path.is_absolute():
|
|
192
|
+
project_path = raw_project_path.resolve()
|
|
193
|
+
else:
|
|
194
|
+
project_path = (Path.cwd() / raw_project_path).resolve()
|
|
195
|
+
relative_project_path: Path = Path(os.path.relpath(project_path, start=output_dir))
|
|
196
|
+
return tuple(relative_project_path.parts)
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def generator_main(argv: Sequence[str] | None = None) -> int:
|
|
200
|
+
"""CLI wrapper compatible with legacy generate_notebook argument shape."""
|
|
201
|
+
|
|
202
|
+
parser: argparse.ArgumentParser = argparse.ArgumentParser(
|
|
203
|
+
description="Generate a Jupyter notebook or Matlab script template.",
|
|
204
|
+
)
|
|
205
|
+
parser.add_argument(
|
|
206
|
+
"language",
|
|
207
|
+
choices=[language.value for language in NotebookLanguage],
|
|
208
|
+
help='Output language ("JupyterNotebook" or "Matlab").',
|
|
209
|
+
)
|
|
210
|
+
parser.add_argument(
|
|
211
|
+
"type",
|
|
212
|
+
choices=[template_kind.value for template_kind in NotebookTemplateKind],
|
|
213
|
+
help='Template kind ("Driver", "ParameterScan", "Optimization").',
|
|
214
|
+
)
|
|
215
|
+
parser.add_argument(
|
|
216
|
+
"path",
|
|
217
|
+
help="Output stem path without extension.",
|
|
218
|
+
)
|
|
219
|
+
parser.add_argument(
|
|
220
|
+
"project",
|
|
221
|
+
help="Project file name used inside generated template.",
|
|
222
|
+
)
|
|
223
|
+
parser.add_argument(
|
|
224
|
+
"json_file",
|
|
225
|
+
help="Path to legacy MissingKeys JSON payload.",
|
|
226
|
+
)
|
|
227
|
+
parser.add_argument(
|
|
228
|
+
"--optimizer-cloud-token",
|
|
229
|
+
default=None,
|
|
230
|
+
help=(
|
|
231
|
+
"Optional optimizer token override for generated optimization " "notebooks."
|
|
232
|
+
),
|
|
233
|
+
)
|
|
234
|
+
parser.add_argument(
|
|
235
|
+
"--kernel-name",
|
|
236
|
+
default="python3",
|
|
237
|
+
help="Notebook kernel name used in generated notebook metadata.",
|
|
238
|
+
)
|
|
239
|
+
|
|
240
|
+
parsed = parser.parse_args(list(argv) if argv is not None else None)
|
|
241
|
+
|
|
242
|
+
resolved_token: str | None = parsed.optimizer_cloud_token
|
|
243
|
+
if resolved_token is None:
|
|
244
|
+
resolved_token = os.getenv("JCMOPTIMIZER_TOKEN")
|
|
245
|
+
|
|
246
|
+
output_file: Path = generate_legacy_notebook_template(
|
|
247
|
+
language=parsed.language,
|
|
248
|
+
template_kind=parsed.type,
|
|
249
|
+
output_stem=parsed.path,
|
|
250
|
+
project=parsed.project,
|
|
251
|
+
missing_keys_json_file=parsed.json_file,
|
|
252
|
+
optimizer_cloud_token=resolved_token,
|
|
253
|
+
notebook_kernel_name=parsed.kernel_name,
|
|
254
|
+
)
|
|
255
|
+
print(str(output_file))
|
|
256
|
+
print(output_file.read_text(encoding="utf-8"))
|
|
257
|
+
return 0
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def _normalize_language(language: NotebookLanguage | str) -> NotebookLanguage:
|
|
261
|
+
"""Normalize/validate language enum input."""
|
|
262
|
+
|
|
263
|
+
if isinstance(language, NotebookLanguage):
|
|
264
|
+
return language
|
|
265
|
+
try:
|
|
266
|
+
return NotebookLanguage(language)
|
|
267
|
+
except ValueError as error:
|
|
268
|
+
raise NotebookConfigurationError(
|
|
269
|
+
f"Unsupported notebook language: {language!r}"
|
|
270
|
+
) from error
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
def _normalize_template_kind(
|
|
274
|
+
template_kind: NotebookTemplateKind | str,
|
|
275
|
+
) -> NotebookTemplateKind:
|
|
276
|
+
"""Normalize/validate template-kind enum input."""
|
|
277
|
+
|
|
278
|
+
if isinstance(template_kind, NotebookTemplateKind):
|
|
279
|
+
return template_kind
|
|
280
|
+
try:
|
|
281
|
+
return NotebookTemplateKind(template_kind)
|
|
282
|
+
except ValueError as error:
|
|
283
|
+
raise NotebookConfigurationError(
|
|
284
|
+
f"Unsupported notebook template kind: {template_kind!r}"
|
|
285
|
+
) from error
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def _resolve_template_filename(
|
|
289
|
+
*,
|
|
290
|
+
language: NotebookLanguage,
|
|
291
|
+
template_kind: NotebookTemplateKind,
|
|
292
|
+
) -> str:
|
|
293
|
+
"""Resolve concrete template filename from language/workflow selectors."""
|
|
294
|
+
|
|
295
|
+
key: tuple[NotebookLanguage, NotebookTemplateKind] = (language, template_kind)
|
|
296
|
+
try:
|
|
297
|
+
return _TEMPLATE_FILE_MAP[key]
|
|
298
|
+
except KeyError as error:
|
|
299
|
+
raise NotebookConfigurationError(
|
|
300
|
+
f"No template registered for language={language} kind={template_kind}."
|
|
301
|
+
) from error
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
def _import_jinja2() -> Any:
|
|
305
|
+
"""Import Jinja2 lazily so base runtime does not require it by default."""
|
|
306
|
+
|
|
307
|
+
try:
|
|
308
|
+
import jinja2
|
|
309
|
+
except ModuleNotFoundError as error:
|
|
310
|
+
raise NotebookRuntimeError(
|
|
311
|
+
"Jinja2 is required for notebook template generation. "
|
|
312
|
+
"Install build dependencies before using this helper."
|
|
313
|
+
) from error
|
|
314
|
+
return cast(Any, jinja2)
|
|
315
|
+
|
|
316
|
+
|
|
317
|
+
def _load_missing_keys(json_file: Path) -> list[MissingKeyParameter]:
|
|
318
|
+
"""Load and validate legacy `MissingKeys` parameter schema from JSON."""
|
|
319
|
+
|
|
320
|
+
if not json_file.is_file():
|
|
321
|
+
raise NotebookConfigurationError(
|
|
322
|
+
f"MissingKeys JSON file does not exist: {json_file}"
|
|
323
|
+
)
|
|
324
|
+
|
|
325
|
+
payload: object = json.loads(json_file.read_text(encoding="utf-8"))
|
|
326
|
+
if not isinstance(payload, dict):
|
|
327
|
+
raise NotebookConfigurationError(
|
|
328
|
+
"MissingKeys payload must be a JSON object with key `MissingKeys`."
|
|
329
|
+
)
|
|
330
|
+
|
|
331
|
+
raw_missing_keys: object | None = payload.get("MissingKeys")
|
|
332
|
+
if not isinstance(raw_missing_keys, list):
|
|
333
|
+
raise NotebookConfigurationError(
|
|
334
|
+
"MissingKeys payload must define `MissingKeys` as a list."
|
|
335
|
+
)
|
|
336
|
+
|
|
337
|
+
normalized: list[MissingKeyParameter] = []
|
|
338
|
+
index: int
|
|
339
|
+
raw_entry: object
|
|
340
|
+
for index, raw_entry in enumerate(raw_missing_keys):
|
|
341
|
+
normalized.append(
|
|
342
|
+
_normalize_missing_key_entry(index=index, raw_entry=raw_entry)
|
|
343
|
+
)
|
|
344
|
+
return normalized
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
def _normalize_missing_key_entry(
|
|
348
|
+
*,
|
|
349
|
+
index: int,
|
|
350
|
+
raw_entry: object,
|
|
351
|
+
) -> MissingKeyParameter:
|
|
352
|
+
"""Validate one legacy MissingKeys entry and normalize expression fields."""
|
|
353
|
+
|
|
354
|
+
if not isinstance(raw_entry, dict):
|
|
355
|
+
raise NotebookConfigurationError(f"MissingKeys[{index}] must be a JSON object.")
|
|
356
|
+
|
|
357
|
+
raw_name: object | None = raw_entry.get("name")
|
|
358
|
+
if not isinstance(raw_name, str) or not raw_name.strip():
|
|
359
|
+
raise NotebookConfigurationError(
|
|
360
|
+
f"MissingKeys[{index}] must define a non-empty string `name`."
|
|
361
|
+
)
|
|
362
|
+
|
|
363
|
+
raw_type: object | None = raw_entry.get("type")
|
|
364
|
+
normalized_type: str = "real"
|
|
365
|
+
if isinstance(raw_type, str) and raw_type.strip():
|
|
366
|
+
normalized_type = raw_type.strip()
|
|
367
|
+
|
|
368
|
+
raw_value: object | None = raw_entry.get("value")
|
|
369
|
+
normalized_value: str | None
|
|
370
|
+
if raw_value is None:
|
|
371
|
+
normalized_value = None
|
|
372
|
+
elif isinstance(raw_value, str):
|
|
373
|
+
normalized_value = raw_value
|
|
374
|
+
else:
|
|
375
|
+
normalized_value = json.dumps(raw_value)
|
|
376
|
+
|
|
377
|
+
return MissingKeyParameter(
|
|
378
|
+
name=raw_name.strip(),
|
|
379
|
+
type=normalized_type,
|
|
380
|
+
value=normalized_value,
|
|
381
|
+
)
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# SPDX-License-Identifier: MIT
|
|
2
|
+
# Copyright (c) 2001-2026 JCMwave GmbH
|
|
3
|
+
|
|
4
|
+
"""Guarded Jupyter launcher with parent-PID lifecycle binding."""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import argparse
|
|
9
|
+
import importlib
|
|
10
|
+
import os
|
|
11
|
+
import platform
|
|
12
|
+
import signal
|
|
13
|
+
import sys
|
|
14
|
+
import time
|
|
15
|
+
from collections.abc import Sequence
|
|
16
|
+
from multiprocessing import Process
|
|
17
|
+
from typing import Any
|
|
18
|
+
|
|
19
|
+
from .errors import NotebookConfigurationError
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def is_pid_running(pid: int) -> bool:
|
|
23
|
+
"""Return whether process identifier exists on the current platform."""
|
|
24
|
+
|
|
25
|
+
if pid <= 0:
|
|
26
|
+
return False
|
|
27
|
+
if platform.system() == "Windows":
|
|
28
|
+
return _is_pid_running_on_windows(pid)
|
|
29
|
+
return _is_pid_running_on_unix(pid)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _is_pid_running_on_unix(pid: int) -> bool:
|
|
33
|
+
"""Check process existence on Unix platforms via signal 0 probe."""
|
|
34
|
+
|
|
35
|
+
try:
|
|
36
|
+
os.kill(pid, 0)
|
|
37
|
+
except OSError:
|
|
38
|
+
return False
|
|
39
|
+
return True
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _is_pid_running_on_windows(pid: int) -> bool:
|
|
43
|
+
"""Check process existence on Windows via EnumProcesses API."""
|
|
44
|
+
|
|
45
|
+
import ctypes
|
|
46
|
+
import ctypes.wintypes
|
|
47
|
+
|
|
48
|
+
# `WinDLL` is Windows-only and not fully typed in typeshed.
|
|
49
|
+
psapi = ctypes.WinDLL("Psapi.dll") # type: ignore[attr-defined]
|
|
50
|
+
enum_processes = psapi.EnumProcesses
|
|
51
|
+
enum_processes.restype = ctypes.wintypes.BOOL
|
|
52
|
+
|
|
53
|
+
count: int = 64
|
|
54
|
+
while True:
|
|
55
|
+
process_ids = (ctypes.wintypes.DWORD * count)()
|
|
56
|
+
buffer_bytes: int = ctypes.sizeof(process_ids)
|
|
57
|
+
bytes_returned = ctypes.wintypes.DWORD()
|
|
58
|
+
if enum_processes(
|
|
59
|
+
ctypes.byref(process_ids),
|
|
60
|
+
buffer_bytes,
|
|
61
|
+
ctypes.byref(bytes_returned),
|
|
62
|
+
):
|
|
63
|
+
if pid in process_ids:
|
|
64
|
+
return True
|
|
65
|
+
if bytes_returned.value < buffer_bytes:
|
|
66
|
+
break
|
|
67
|
+
count *= 2
|
|
68
|
+
continue
|
|
69
|
+
raise EnvironmentError("Call to EnumProcesses failed")
|
|
70
|
+
|
|
71
|
+
return False
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def launch_notebook_with_parent_monitor(
|
|
75
|
+
*,
|
|
76
|
+
parent_pid: int,
|
|
77
|
+
notebook_argv: Sequence[str],
|
|
78
|
+
poll_interval_seconds: float = 5.0,
|
|
79
|
+
) -> int:
|
|
80
|
+
"""Launch notebook app and keep it alive only while `parent_pid` exists."""
|
|
81
|
+
|
|
82
|
+
if parent_pid <= 0:
|
|
83
|
+
raise NotebookConfigurationError(
|
|
84
|
+
f"Parent PID must be a positive integer, got {parent_pid}."
|
|
85
|
+
)
|
|
86
|
+
if poll_interval_seconds <= 0.0:
|
|
87
|
+
raise NotebookConfigurationError("Polling interval must be positive.")
|
|
88
|
+
|
|
89
|
+
app_process: Process = Process(
|
|
90
|
+
target=_run_notebook_app,
|
|
91
|
+
args=(list(notebook_argv),),
|
|
92
|
+
daemon=True,
|
|
93
|
+
)
|
|
94
|
+
app_process.start()
|
|
95
|
+
|
|
96
|
+
_install_signal_handlers(app_process)
|
|
97
|
+
|
|
98
|
+
while True:
|
|
99
|
+
if not is_pid_running(parent_pid):
|
|
100
|
+
break
|
|
101
|
+
if not app_process.is_alive():
|
|
102
|
+
break
|
|
103
|
+
time.sleep(poll_interval_seconds)
|
|
104
|
+
|
|
105
|
+
_terminate_process(app_process)
|
|
106
|
+
return 0
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def launcher_main(argv: Sequence[str] | None = None) -> int:
|
|
110
|
+
"""CLI wrapper for guarded notebook launcher."""
|
|
111
|
+
|
|
112
|
+
parser: argparse.ArgumentParser = argparse.ArgumentParser(
|
|
113
|
+
description="Start Jupyter and stop it when the caller PID exits.",
|
|
114
|
+
)
|
|
115
|
+
parser.add_argument(
|
|
116
|
+
"calling_pid",
|
|
117
|
+
type=int,
|
|
118
|
+
help="PID of parent process to monitor.",
|
|
119
|
+
)
|
|
120
|
+
parser.add_argument(
|
|
121
|
+
"notebook_args",
|
|
122
|
+
nargs=argparse.REMAINDER,
|
|
123
|
+
help="Additional arguments passed to notebook app.",
|
|
124
|
+
)
|
|
125
|
+
|
|
126
|
+
parsed = parser.parse_args(list(argv) if argv is not None else None)
|
|
127
|
+
notebook_args: list[str] = list(parsed.notebook_args)
|
|
128
|
+
return launch_notebook_with_parent_monitor(
|
|
129
|
+
parent_pid=parsed.calling_pid,
|
|
130
|
+
notebook_argv=notebook_args,
|
|
131
|
+
)
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def _run_notebook_app(notebook_argv: Sequence[str]) -> None:
|
|
135
|
+
"""Invoke notebook app main routine with explicit argv forwarding."""
|
|
136
|
+
|
|
137
|
+
sys.argv = ["jupyter-notebook", *list(notebook_argv)]
|
|
138
|
+
try:
|
|
139
|
+
notebook_module: Any = importlib.import_module("notebook.app")
|
|
140
|
+
except ModuleNotFoundError as error:
|
|
141
|
+
if error.name != "notebook.app":
|
|
142
|
+
raise
|
|
143
|
+
notebook_module = importlib.import_module("notebook.notebookapp")
|
|
144
|
+
app_main: Any = getattr(notebook_module, "main")
|
|
145
|
+
app_main()
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _install_signal_handlers(process: Process) -> None:
|
|
149
|
+
"""Install termination handlers that stop the notebook child process."""
|
|
150
|
+
|
|
151
|
+
def _handle_signal(_signal_number: int, _frame: object | None) -> None:
|
|
152
|
+
_terminate_process(process)
|
|
153
|
+
raise SystemExit(0)
|
|
154
|
+
|
|
155
|
+
signal.signal(signal.SIGINT, _handle_signal)
|
|
156
|
+
signal.signal(signal.SIGTERM, _handle_signal)
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def _terminate_process(process: Process) -> None:
|
|
160
|
+
"""Terminate notebook child process if still alive."""
|
|
161
|
+
|
|
162
|
+
if not process.is_alive():
|
|
163
|
+
return
|
|
164
|
+
process.terminate()
|
|
165
|
+
process.join(timeout=5.0)
|
|
166
|
+
if process.is_alive():
|
|
167
|
+
process.kill()
|
|
168
|
+
process.join(timeout=2.0)
|
|
File without changes
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
{
|
|
2
|
+
"cells": [
|
|
3
|
+
{
|
|
4
|
+
"cell_type": "markdown",
|
|
5
|
+
"metadata": {},
|
|
6
|
+
"source": [
|
|
7
|
+
{% block header %}
|
|
8
|
+
"<h1>Preparation of Data Analysis</h1>\n",
|
|
9
|
+
"This notebook was generated by the internal JCMsuite notebook converter.\n",
|
|
10
|
+
"Run cells with [Shift][Enter]. Optional cells are <span style=\"{{style.optional}}\">gray</span>. Cells that require user input are <span style=\"{{style.user_input}}\">red</span>.\n",
|
|
11
|
+
{% endblock %}
|
|
12
|
+
"\n",
|
|
13
|
+
"<h2>Import of Packages</h2>\n",
|
|
14
|
+
"This cell imports required packages. Add your own packages if needed."
|
|
15
|
+
]
|
|
16
|
+
},
|
|
17
|
+
{
|
|
18
|
+
"cell_type": "code",
|
|
19
|
+
"execution_count": null,
|
|
20
|
+
"metadata": {},
|
|
21
|
+
"outputs": [],
|
|
22
|
+
"source": [
|
|
23
|
+
"import numpy as np\n",
|
|
24
|
+
"from pprint import pprint\n",
|
|
25
|
+
"\n",
|
|
26
|
+
{% block import %}
|
|
27
|
+
{% endblock %}
|
|
28
|
+
"from jcmsuite import solve, view\n",
|
|
29
|
+
"from jcmsuite.daemon import Workstation, handler\n"
|
|
30
|
+
]
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
"cell_type": "markdown",
|
|
34
|
+
"metadata": {},
|
|
35
|
+
"source": [
|
|
36
|
+
"<h2>Configuration of Computational Resources</h2>\n",
|
|
37
|
+
"This cell declares the daemon resources used for solves."
|
|
38
|
+
]
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"cell_type": "code",
|
|
42
|
+
"execution_count": null,
|
|
43
|
+
"metadata": {
|
|
44
|
+
"scrolled": false
|
|
45
|
+
},
|
|
46
|
+
"outputs": [],
|
|
47
|
+
"source": [
|
|
48
|
+
"d = handler()\n",
|
|
49
|
+
"d.resources.add(Workstation(hostname='localhost', multiplicity=1, n_threads=4))"
|
|
50
|
+
]
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"cell_type": "markdown",
|
|
54
|
+
"metadata": {},
|
|
55
|
+
"source": [
|
|
56
|
+
"<h2>Definition of Default Parameters</h2>\n",
|
|
57
|
+
"<div style=\"{{style.user_input}}\">Define default values of all project parameters (keys).</div>"
|
|
58
|
+
]
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
"cell_type": "code",
|
|
62
|
+
"execution_count": null,
|
|
63
|
+
"metadata": {},
|
|
64
|
+
"outputs": [],
|
|
65
|
+
"source": [
|
|
66
|
+
"default_keys = {\n",
|
|
67
|
+
{% for param in params -%}
|
|
68
|
+
" '{{ param.name }}': {{param.value if param.value is not none else "_{}_".format(param.type)}}{{ "," if not loop.last }}\n",
|
|
69
|
+
{%- endfor %}
|
|
70
|
+
"}"
|
|
71
|
+
]
|
|
72
|
+
},
|
|
73
|
+
{% block initial_preview %}
|
|
74
|
+
{
|
|
75
|
+
"cell_type": "markdown",
|
|
76
|
+
"metadata": {},
|
|
77
|
+
"source": [
|
|
78
|
+
"<div style=\"{{style.optional}}\">Run this cell to inspect one solve with default parameters.</div>"
|
|
79
|
+
]
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
"cell_type": "code",
|
|
83
|
+
"execution_count": null,
|
|
84
|
+
"metadata": {
|
|
85
|
+
"scrolled": true
|
|
86
|
+
},
|
|
87
|
+
"outputs": [],
|
|
88
|
+
"source": [
|
|
89
|
+
"with d:\n",
|
|
90
|
+
" result = await solve('{{project}}', keys=default_keys, asynchronous=True, wait_progress=True)\n",
|
|
91
|
+
"\n",
|
|
92
|
+
"print('SolveResult summary:')\n",
|
|
93
|
+
"pprint(result.to_df(detail='summary').to_dict(orient='records')[0])\n",
|
|
94
|
+
"if result.file is not None:\n",
|
|
95
|
+
" await view(result.file, asynchronous=True)"
|
|
96
|
+
]
|
|
97
|
+
}
|
|
98
|
+
{% endblock %}
|
|
99
|
+
{% block task %}{% endblock %}
|
|
100
|
+
],
|
|
101
|
+
"metadata": {
|
|
102
|
+
"kernelspec": {
|
|
103
|
+
"display_name": "Python 3",
|
|
104
|
+
"language": "python",
|
|
105
|
+
"name": "{{ kernel_name }}"
|
|
106
|
+
},
|
|
107
|
+
"language_info": {
|
|
108
|
+
"codemirror_mode": {
|
|
109
|
+
"name": "ipython",
|
|
110
|
+
"version": 3
|
|
111
|
+
},
|
|
112
|
+
"file_extension": ".py",
|
|
113
|
+
"mimetype": "text/x-python",
|
|
114
|
+
"name": "python",
|
|
115
|
+
"nbconvert_exporter": "python",
|
|
116
|
+
"pygments_lexer": "ipython3",
|
|
117
|
+
"version": "3"
|
|
118
|
+
}
|
|
119
|
+
},
|
|
120
|
+
"nbformat": 4,
|
|
121
|
+
"nbformat_minor": 2
|
|
122
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
% This script file was generated using JCMsuite notebook converter.
|
|
2
|
+
% Please, open it with your local Matlab application.
|
|
3
|
+
addpath(fullfile(getenv('JCMROOT'), 'ThirdPartySupport', 'Matlab'));
|
|
4
|
+
script_dir = fileparts(mfilename('fullpath'));
|
|
5
|
+
project_file = fullfile(script_dir{% for part in matlab_project_parts %}, '{{ part }}'{% endfor %});
|
|
6
|
+
|
|
7
|
+
%% register a new computer resource
|
|
8
|
+
jcmwave_daemon_shutdown();
|
|
9
|
+
jcmwave_daemon_add_workstation('Hostname', 'localhost', ...
|
|
10
|
+
'Multiplicity', 1, ...
|
|
11
|
+
'NThreads', 4);
|
|
12
|
+
|
|
13
|
+
%% define default key values
|
|
14
|
+
{% for param in params -%}
|
|
15
|
+
default_keys.{{'.'.join(param.name.split('/'))}} = {{param.value if param.value is not none else '_{}_'.format(param.type)}};
|
|
16
|
+
{% endfor %}
|
|
17
|
+
|
|
18
|
+
%% Inspect results with default parameters
|
|
19
|
+
job_id = jcmwave_solve(project_file, default_keys);
|
|
20
|
+
[results, logs] = jcmwave_daemon_wait([job_id]);
|
|
21
|
+
result = results{1};
|
|
22
|
+
for ii=1:length(result)
|
|
23
|
+
{% raw %}fprintf("=== Content of result{%d} ===",ii);{% endraw %}
|
|
24
|
+
result{ii}
|
|
25
|
+
end
|
|
26
|
+
jcmwave_view(result{1}.file);
|
|
27
|
+
|
|
28
|
+
{% block task %}{% endblock %}
|
|
29
|
+
|
|
30
|
+
%% shut down daemon
|
|
31
|
+
jcmwave_daemon_shutdown();
|
|
32
|
+
{% block postamble %}{% endblock %}
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
{% extends "BaseTemplate.ipynb.j2" %}
|
|
2
|
+
|
|
3
|
+
{% block initial_preview %}
|
|
4
|
+
{
|
|
5
|
+
"cell_type": "markdown",
|
|
6
|
+
"metadata": {},
|
|
7
|
+
"source": [
|
|
8
|
+
"<div style=\"{{style.optional}}\">Run this cell to inspect one solve with default parameters.</div>"
|
|
9
|
+
]
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"cell_type": "code",
|
|
13
|
+
"execution_count": null,
|
|
14
|
+
"metadata": {
|
|
15
|
+
"scrolled": true
|
|
16
|
+
},
|
|
17
|
+
"outputs": [],
|
|
18
|
+
"source": [
|
|
19
|
+
"with d:\n",
|
|
20
|
+
" result = await solve('{{project}}', keys=default_keys, asynchronous=True, wait_progress=True)\n",
|
|
21
|
+
"\n",
|
|
22
|
+
"print('SolveResult summary:')\n",
|
|
23
|
+
"pprint(result.to_df(detail='summary').to_dict(orient='records')[0])\n",
|
|
24
|
+
"if result.file is not None:\n",
|
|
25
|
+
" await view(result.file, asynchronous=True)"
|
|
26
|
+
]
|
|
27
|
+
}
|
|
28
|
+
{% endblock %}
|
|
29
|
+
|
|
30
|
+
{% block task %}
|
|
31
|
+
,
|
|
32
|
+
{
|
|
33
|
+
"cell_type": "markdown",
|
|
34
|
+
"metadata": {},
|
|
35
|
+
"source": [
|
|
36
|
+
"<h1>Parameter Optimization</h1>\n",
|
|
37
|
+
"This section sets up an optimization study using the default optimizer configuration, with a local fallback."
|
|
38
|
+
]
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"cell_type": "code",
|
|
42
|
+
"execution_count": null,
|
|
43
|
+
"metadata": {},
|
|
44
|
+
"outputs": [],
|
|
45
|
+
"source": [
|
|
46
|
+
"from jcmoptimizer import Client, Server\n",
|
|
47
|
+
"\n",
|
|
48
|
+
{% if optimizer_cloud_token %}
|
|
49
|
+
"token = '{{ optimizer_cloud_token }}'\n",
|
|
50
|
+
"server = Server(token=token)\n",
|
|
51
|
+
"client = Client(host=server.host, token=token)\n",
|
|
52
|
+
{% else %}
|
|
53
|
+
"server = Server()\n",
|
|
54
|
+
"client = Client(host=server.host)\n",
|
|
55
|
+
{% endif %}
|
|
56
|
+
"# Local server fallback: comment the previous line(s) and uncomment the next two lines.\n",
|
|
57
|
+
"# server = Server(server_location='local')\n",
|
|
58
|
+
"# client = Client(host=server.host)\n",
|
|
59
|
+
"\n",
|
|
60
|
+
"design_space = [\n",
|
|
61
|
+
{% for param in params if param.type in ['real','complex','integer'] -%}
|
|
62
|
+
" {'name': '{{ param.name }}', 'type': {% if param.type=='integer' %}'discrete', 'domain': [_val1_, _val2_, _val3_]}{% else %}'continuous', 'domain': (_lower_, _upper_)}{% endif %}{{ ',' if not loop.last }}\n",
|
|
63
|
+
{%- endfor %}
|
|
64
|
+
"]\n",
|
|
65
|
+
"\n",
|
|
66
|
+
"study = client.create_study(\n",
|
|
67
|
+
" design_space=design_space,\n",
|
|
68
|
+
" study_name='Optimization study',\n",
|
|
69
|
+
" study_id='{{ study_id }}',\n",
|
|
70
|
+
" driver='BayesianOptimization',\n",
|
|
71
|
+
" save_dir='.',\n",
|
|
72
|
+
")\n",
|
|
73
|
+
"study.configure(max_iter=10, num_parallel=2)"
|
|
74
|
+
]
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"cell_type": "markdown",
|
|
78
|
+
"metadata": {},
|
|
79
|
+
"source": [
|
|
80
|
+
"<h2>Objective Function</h2>\n",
|
|
81
|
+
"<div style=\"{{style.user_input}}\">Define objective extraction from the solve result.</div>"
|
|
82
|
+
]
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
"cell_type": "code",
|
|
86
|
+
"execution_count": null,
|
|
87
|
+
"metadata": {},
|
|
88
|
+
"outputs": [],
|
|
89
|
+
"source": [
|
|
90
|
+
"async def objective(study, **params):\n",
|
|
91
|
+
" keys = default_keys.copy()\n",
|
|
92
|
+
" keys.update(params)\n",
|
|
93
|
+
"\n",
|
|
94
|
+
" result = await solve('{{project}}', keys=keys, temporary=True, asynchronous=True)\n",
|
|
95
|
+
"\n",
|
|
96
|
+
" pp_df = result.postprocesses[0].to_df()\n",
|
|
97
|
+
"\n",
|
|
98
|
+
" # Define objective to minimize here.\n",
|
|
99
|
+
" # Example: objective_value = pp_df[\"column_name\"].iloc[0]\n",
|
|
100
|
+
" objective_value = _objective_value_\n",
|
|
101
|
+
" observation = study.new_observation()\n",
|
|
102
|
+
" observation.add(objective_value)\n",
|
|
103
|
+
" return observation\n",
|
|
104
|
+
"\n",
|
|
105
|
+
"study.set_evaluator(objective)"
|
|
106
|
+
]
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
"cell_type": "code",
|
|
110
|
+
"execution_count": null,
|
|
111
|
+
"metadata": {
|
|
112
|
+
"scrolled": true
|
|
113
|
+
},
|
|
114
|
+
"outputs": [],
|
|
115
|
+
"source": [
|
|
116
|
+
"with d:\n",
|
|
117
|
+
" study.run()"
|
|
118
|
+
]
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
"cell_type": "code",
|
|
122
|
+
"execution_count": null,
|
|
123
|
+
"metadata": {},
|
|
124
|
+
"outputs": [],
|
|
125
|
+
"source": [
|
|
126
|
+
"best = study.driver.best_sample\n",
|
|
127
|
+
"\n",
|
|
128
|
+
"print(f\"Best sample at: {% for param in params if param.type in ['real','complex','integer'] %}{{ param.name }} = {best['{{ param.name }}']:.3f}{% if not loop.last %}, {% endif %}{% endfor %}\")\n",
|
|
129
|
+
"\n",
|
|
130
|
+
"# min_params = study.info()['min_params']\n",
|
|
131
|
+
"keys = default_keys.copy()\n",
|
|
132
|
+
"keys.update(best)\n",
|
|
133
|
+
"with d:\n",
|
|
134
|
+
" best_result = await solve('{{project}}', keys=keys, asynchronous=True)\n",
|
|
135
|
+
"if best_result.file is not None:\n",
|
|
136
|
+
" await view(best_result.file, asynchronous=True)"
|
|
137
|
+
]
|
|
138
|
+
}
|
|
139
|
+
{% endblock %}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
{% extends "BaseTemplate.m" %}
|
|
2
|
+
|
|
3
|
+
{% block task %}
|
|
4
|
+
% TODO: add your local JCMoptimizer Matlab interface path here, e.g.
|
|
5
|
+
% addpath('/path/to/JCMoptimizer/interface/matlab');
|
|
6
|
+
|
|
7
|
+
server = jcmoptimizer.Server();
|
|
8
|
+
%% For a local fallback please comment in the following line and comment out the line above
|
|
9
|
+
% server = jcmoptimizer.Server('server_location', 'local');
|
|
10
|
+
client = jcmoptimizer.Client('host', server.host);
|
|
11
|
+
|
|
12
|
+
%% Definition of the search domain
|
|
13
|
+
design_space = {...
|
|
14
|
+
{% for param in params if param.type in ['real','complex','integer'] %}
|
|
15
|
+
struct('name', '{{param.name}}', 'type', '{% if param.type=='integer' %}discrete{% else %}continuous{% endif %}', 'domain', {% if param.type=='integer' %}[val1_,val2_,...]{% else %}[lower_,upper_]{% endif %}), ...
|
|
16
|
+
{% endfor %}
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
%% Creation of the study object
|
|
20
|
+
study = client.create_study( ...
|
|
21
|
+
'design_space', design_space, ...
|
|
22
|
+
'driver', 'BayesianOptimization', ...
|
|
23
|
+
'study_name', 'Standard Bayesian optimization', ...
|
|
24
|
+
'study_id', 'vanilla_bayesian_optimization');
|
|
25
|
+
|
|
26
|
+
%% Configure study parameters
|
|
27
|
+
study.configure('max_iter', 20);
|
|
28
|
+
|
|
29
|
+
%% Run the minimization
|
|
30
|
+
study.set_evaluator(@evaluate);
|
|
31
|
+
study.run();
|
|
32
|
+
|
|
33
|
+
best = study.driver.best_sample;
|
|
34
|
+
fprintf('Best sample at {% for param in params if param.type in ['real','complex','integer'] %}{{param.name}}=%0.3e{% if not loop.last %}, {% endif %}{% endfor %}\n', {% for param in params if param.type in ['real','complex','integer'] %}best.{{param.name}}{% if not loop.last %}, {% endif %}{% endfor %})
|
|
35
|
+
|
|
36
|
+
%% Print information on all found local minima
|
|
37
|
+
minima = study.driver.get_minima('num_initial_samples', 20);
|
|
38
|
+
array2table(cell2mat(struct2cell(minima)).', 'VariableNames', fieldnames(minima))
|
|
39
|
+
|
|
40
|
+
client.shutdown_server();
|
|
41
|
+
{% endblock %}
|
|
42
|
+
|
|
43
|
+
{% block postamble %}
|
|
44
|
+
%% Evaluation of the black-box function for specified design parameters
|
|
45
|
+
function observation = evaluate(study, sample)
|
|
46
|
+
|
|
47
|
+
pause(2); % make objective expensive
|
|
48
|
+
observation = study.new_observation();
|
|
49
|
+
{% for param in params if param.type in ['real','complex','integer'] %}
|
|
50
|
+
{{param.name}} = sample.{{param.name}};
|
|
51
|
+
{% if param.type=='integer' -%}
|
|
52
|
+
{%- endif -%}
|
|
53
|
+
{%- endfor %}
|
|
54
|
+
observation.add(computed_value_); % Please, define the objective here. This may be the output of a post process or a function of several output values. E.g., -1e32*real(result{2}.ElectricFieldEnergy{1}(1));
|
|
55
|
+
end
|
|
56
|
+
{% endblock %}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
{% extends "BaseTemplate.ipynb.j2" %}
|
|
2
|
+
|
|
3
|
+
{% block import %}
|
|
4
|
+
"import collections\n",
|
|
5
|
+
"import itertools\n",
|
|
6
|
+
"import matplotlib.pyplot as plt\n",
|
|
7
|
+
{% endblock %}
|
|
8
|
+
|
|
9
|
+
{% block task %}
|
|
10
|
+
,
|
|
11
|
+
{
|
|
12
|
+
"cell_type": "markdown",
|
|
13
|
+
"metadata": {},
|
|
14
|
+
"source": [
|
|
15
|
+
"<h1>Parameter Scan</h1>\n",
|
|
16
|
+
"This section runs a multidimensional scan with modern batch solve syntax."
|
|
17
|
+
]
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"cell_type": "code",
|
|
21
|
+
"execution_count": null,
|
|
22
|
+
"metadata": {},
|
|
23
|
+
"outputs": [],
|
|
24
|
+
"source": [
|
|
25
|
+
"scan_domain = collections.OrderedDict()\n",
|
|
26
|
+
{% for param in params if param.type in ['real','complex','integer'] -%}
|
|
27
|
+
{% set line_prefix = "# " if loop.index > 2 else "" -%}
|
|
28
|
+
{%- if param.type == 'integer' -%}
|
|
29
|
+
"{{ line_prefix }}scan_domain['{{ param.name }}'] = range(_lower_, _upper_, _step_)\n",
|
|
30
|
+
{%- else -%}
|
|
31
|
+
"{{ line_prefix }}scan_domain['{{ param.name }}'] = np.arange(_lower_, _upper_, _step_)\n",
|
|
32
|
+
{%- endif -%}
|
|
33
|
+
{%- endfor %}
|
|
34
|
+
"\n",
|
|
35
|
+
"scan_keys = []\n",
|
|
36
|
+
"scan_axes = list(scan_domain.keys())\n",
|
|
37
|
+
"for point in itertools.product(*scan_domain.values()):\n",
|
|
38
|
+
" keys = default_keys.copy()\n",
|
|
39
|
+
" for axis_name, axis_value in zip(scan_axes, point, strict=True):\n",
|
|
40
|
+
" keys[axis_name] = axis_value\n",
|
|
41
|
+
" scan_keys.append(keys)"
|
|
42
|
+
]
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
"cell_type": "markdown",
|
|
46
|
+
"metadata": {},
|
|
47
|
+
"source": [
|
|
48
|
+
"<h2>Run Scan</h2>\n",
|
|
49
|
+
"Batch results are returned as `BatchSolveResult` and optionally persisted in a Resultbag."
|
|
50
|
+
]
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
"cell_type": "code",
|
|
54
|
+
"execution_count": null,
|
|
55
|
+
"metadata": {
|
|
56
|
+
"scrolled": true
|
|
57
|
+
},
|
|
58
|
+
"outputs": [],
|
|
59
|
+
"source": [
|
|
60
|
+
"from jcmsuite.results import Resultbag\n",
|
|
61
|
+
"\n",
|
|
62
|
+
"resultbag = Resultbag('resultbag.jcmrb')\n",
|
|
63
|
+
"with d:\n",
|
|
64
|
+
" batch = await solve('{{project}}', keys=scan_keys, temporary=True, resultbag=resultbag, on_error='collect', asynchronous=True)\n",
|
|
65
|
+
"\n",
|
|
66
|
+
"summary_df = batch.to_df(detail='summary')\n",
|
|
67
|
+
"summary_df.head()"
|
|
68
|
+
]
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
"cell_type": "markdown",
|
|
72
|
+
"metadata": {},
|
|
73
|
+
"source": [
|
|
74
|
+
"<h2>Plot Results</h2>\n",
|
|
75
|
+
"<div style=\"{{style.user_input}}\">Define an objective from results and visualize it over the scan domain.</div>"
|
|
76
|
+
]
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
"cell_type": "code",
|
|
80
|
+
"execution_count": null,
|
|
81
|
+
"metadata": {},
|
|
82
|
+
"outputs": [],
|
|
83
|
+
"source": [
|
|
84
|
+
"# Show postprocess data from one postprocess section.\n",
|
|
85
|
+
"# Replace indices/column names with your own objective extraction.\n",
|
|
86
|
+
"pp_df = batch.postprocesses[_postprocess_index_].to_df()\n",
|
|
87
|
+
"pp_df.head()"
|
|
88
|
+
]
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
"cell_type": "code",
|
|
92
|
+
"execution_count": null,
|
|
93
|
+
"metadata": {},
|
|
94
|
+
"outputs": [],
|
|
95
|
+
"source": [
|
|
96
|
+
"# Example objective column access.\n",
|
|
97
|
+
"pp_df['_result_column_']"
|
|
98
|
+
]
|
|
99
|
+
}
|
|
100
|
+
{% endblock %}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
{% extends "BaseTemplate.m" %}
|
|
2
|
+
|
|
3
|
+
{% block task %}
|
|
4
|
+
%% create resultbag. Results will be stored in file ./resultbag.mat
|
|
5
|
+
resultbag = jcmwave_resultbag('resultbag.mat');
|
|
6
|
+
|
|
7
|
+
%% define set of keys for a multi-dimensional parameter scan
|
|
8
|
+
{% for param in params if param.type in ['real','complex','integer'] %}
|
|
9
|
+
{% if loop.index > 2 -%}%{%- endif -%}
|
|
10
|
+
range.{{param.name}} = lower_:steps_size_:upper_;
|
|
11
|
+
{%- endfor %}
|
|
12
|
+
|
|
13
|
+
% Define 2D scan grid. This expression works similarly also for
|
|
14
|
+
% higher-dimensional scans
|
|
15
|
+
[
|
|
16
|
+
{%- for param in params if param.type in ['real','complex','integer'] -%}
|
|
17
|
+
{%- if loop.index <= 2 -%}
|
|
18
|
+
scan.{{param.name}}{{ "," if loop.index<2 and not loop.last }}
|
|
19
|
+
{%- endif -%}
|
|
20
|
+
{%- endfor -%}
|
|
21
|
+
] = ndgrid(
|
|
22
|
+
{%- for param in params if param.type in ['real','complex','integer'] -%}
|
|
23
|
+
{%- if loop.index <= 2 -%}
|
|
24
|
+
range.{{param.name}}{{ "," if loop.index<2 and not loop.last}}
|
|
25
|
+
{%- endif -%}
|
|
26
|
+
{%- endfor -%}
|
|
27
|
+
);
|
|
28
|
+
|
|
29
|
+
% fill a set of keys with scan values
|
|
30
|
+
scan_names = fieldnames(scan);
|
|
31
|
+
keyset = repmat(default_keys, size(scan.(scan_names{1})));
|
|
32
|
+
for ii = 1 : numel(keyset)
|
|
33
|
+
for jj = 1 : numel(scan_names)
|
|
34
|
+
param_name = scan_names{jj};
|
|
35
|
+
keyset(ii).(param_name) = scan.(param_name)(ii);
|
|
36
|
+
end
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
%% run the parameter scan
|
|
40
|
+
job_ids = [];
|
|
41
|
+
for ii = 1 : numel(keyset)
|
|
42
|
+
keys = keyset(ii);
|
|
43
|
+
job_ids(end+1) = jcmwave_solve(project_file, keys, resultbag, 'temporary', 'yes');
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
% jcmwave_daemon_wait adds all results to the resultbag
|
|
47
|
+
jcmwave_daemon_wait(job_ids, resultbag);
|
|
48
|
+
|
|
49
|
+
%% plot results
|
|
50
|
+
data = zeros(
|
|
51
|
+
{%- for param in params if param.type in ['real','complex','integer'] -%}
|
|
52
|
+
{%- if loop.index <= 2 -%}
|
|
53
|
+
length(range.{{param.name}}){{ "," if loop.index<2 and not loop.last}}{{ ",1" if loop.index<2 and loop.last}}
|
|
54
|
+
{%- endif -%}
|
|
55
|
+
{%- endfor -%}
|
|
56
|
+
);
|
|
57
|
+
for ii = 1 : numel(keyset)
|
|
58
|
+
keys = keyset(ii);
|
|
59
|
+
result = resultbag.get_result(keys);
|
|
60
|
+
% Please, define the objective here. This may be the output of
|
|
61
|
+
% a post process or a function of several output values. E.g.,
|
|
62
|
+
% data(ii) = 1e32*real(result{2}.ElectricFieldEnergy{1}(1));
|
|
63
|
+
data(ii) = computed_value_;
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
if size(data,2) == 1
|
|
67
|
+
{% for param in params if param.type in ['real','integer'] -%}
|
|
68
|
+
{%- if loop.index <= 1 -%}
|
|
69
|
+
plot(scan.{{param.name}},data,'+-');
|
|
70
|
+
xlabel('{{param.name}}');
|
|
71
|
+
{%- endif -%}
|
|
72
|
+
{%- endfor %}
|
|
73
|
+
else
|
|
74
|
+
surf(
|
|
75
|
+
{%- for param in params if param.type in ['real','integer'] -%}
|
|
76
|
+
{%- if loop.index <= 2 -%}
|
|
77
|
+
scan.{{param.name}},
|
|
78
|
+
{%- endif -%}
|
|
79
|
+
{%- endfor -%}
|
|
80
|
+
data);
|
|
81
|
+
colorbar;
|
|
82
|
+
{% for param in params if param.type in ['real','integer'] -%}
|
|
83
|
+
{% if loop.index == 1 -%}
|
|
84
|
+
xlabel('{{param.name}}');
|
|
85
|
+
{% elif loop.index == 2 -%}
|
|
86
|
+
ylabel('{{param.name}}');
|
|
87
|
+
{%- endif -%}
|
|
88
|
+
{%- endfor %}
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
{% endblock %}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: jcmsuite-notebooks
|
|
3
|
+
Version: 7.4.2
|
|
4
|
+
Summary: Notebook and Matlab converter tooling for JCMsuite workflows.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Author: Matthias Plock
|
|
7
|
+
Author-email: matthias.plock@jcmwave.com
|
|
8
|
+
Requires-Python: >=3.13
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Science/Research
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
13
|
+
Requires-Dist: jinja2 (>=3.1,<4.0)
|
|
14
|
+
Requires-Dist: notebook (>=7.0.0)
|
|
15
|
+
Project-URL: Documentation, https://docs.jcmwave.com/JCMsuite/html/
|
|
16
|
+
Project-URL: Homepage, https://www.jcmwave.com
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
|
|
19
|
+
# jcmsuite-notebooks
|
|
20
|
+
|
|
21
|
+
Standalone notebook and Matlab template tools for JCMsuite workflows.
|
|
22
|
+
|
|
23
|
+
Use this package to generate notebook or Matlab templates and launch notebooks
|
|
24
|
+
with parent-process monitoring. It provides support tools, not the JCMsuite
|
|
25
|
+
solver interface or a collection of ready-to-run solver tutorials.
|
|
26
|
+
|
|
27
|
+
## What It Provides
|
|
28
|
+
|
|
29
|
+
- notebook template generation helpers,
|
|
30
|
+
- Matlab template generation helpers,
|
|
31
|
+
- guarded notebook-launch support for parent-process-aware workflows,
|
|
32
|
+
- typed exceptions for notebook/converter runtime and configuration errors.
|
|
33
|
+
|
|
34
|
+
## Primary Python Entry Points
|
|
35
|
+
|
|
36
|
+
- `generate_legacy_notebook_template(...)`
|
|
37
|
+
- `generator_main(...)`
|
|
38
|
+
- `launch_notebook_with_parent_monitor(...)`
|
|
39
|
+
- `launcher_main(...)`
|
|
40
|
+
|
|
41
|
+
Python imports use `jcmsuite_notebooks`, for example:
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
from jcmsuite_notebooks import generate_legacy_notebook_template
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Install
|
|
48
|
+
|
|
49
|
+
Requires Python 3.13 or later. Installation includes Jinja2 and Jupyter Notebook.
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
python -m pip install jcmsuite-notebooks
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Relationship To `jcmsuite`
|
|
56
|
+
|
|
57
|
+
Use this package when you specifically need the notebook or Matlab conversion
|
|
58
|
+
tooling as a low-level dependency. For solver/runtime workflows, install the
|
|
59
|
+
main `jcmsuite` package instead.
|
|
60
|
+
|
|
61
|
+
Template generation does not install or run the JCMsuite solver. Running generated
|
|
62
|
+
code requires the runtime and input files used by that code; JCMsuite solver
|
|
63
|
+
operations require a separate JCMsuite installation and license.
|
|
64
|
+
|
|
65
|
+
## Documentation and Support
|
|
66
|
+
|
|
67
|
+
See the [JCMsuite documentation](https://docs.jcmwave.com/JCMsuite/html/) for the
|
|
68
|
+
JCMsuite manuals and tutorials. For product and support information, visit
|
|
69
|
+
[JCMwave](https://www.jcmwave.com).
|
|
70
|
+
|
|
71
|
+
## License
|
|
72
|
+
|
|
73
|
+
This Python package is licensed under the MIT License.
|
|
74
|
+
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
jcmsuite_notebooks/__init__.py,sha256=Ahxezoej1in154_wn_JYLP__eUIFUsV3nWthnewfvpY,810
|
|
2
|
+
jcmsuite_notebooks/_build_info.py,sha256=CNq1YERybHYZ-LCopso2eY7bLiK8DvnHbC3pKsVEU5g,180
|
|
3
|
+
jcmsuite_notebooks/errors.py,sha256=J9cofdl_m5_thUKQmYNomg6qmbo-eR76JPZ-IUfmqo4,515
|
|
4
|
+
jcmsuite_notebooks/generator.py,sha256=gjyn0SppARKJSv53Kg8yf_fOkGTiC4eBxN8gFzv1FGc,12309
|
|
5
|
+
jcmsuite_notebooks/launcher.py,sha256=NR3Do-xciiUWinJJ4lGjmehDSEJGP_c_2cvqvdtQTkw,4818
|
|
6
|
+
jcmsuite_notebooks/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
7
|
+
jcmsuite_notebooks/templates/BaseTemplate.ipynb.j2,sha256=Hn-wHtZS2qHib1L2pugMJQNVWBmfzH70YQC6huAaAIQ,3070
|
|
8
|
+
jcmsuite_notebooks/templates/BaseTemplate.m,sha256=EJCYTSCo42aTKZY8tixLYA1VyzpoJNQQMqN5A9pn8Bo,1183
|
|
9
|
+
jcmsuite_notebooks/templates/DriverTemplate.ipynb.j2,sha256=mJVwX-OQBV_4RETwt30J2XxZNmt1RZSTrE_PODDYktE,194
|
|
10
|
+
jcmsuite_notebooks/templates/DriverTemplate.m,sha256=GyRSfuDeParduJ2t2OO8-2VHk82aA5V8l1nL34J_Cwo,64
|
|
11
|
+
jcmsuite_notebooks/templates/OptimizationTemplate.ipynb.j2,sha256=GkUNrnLdYln3uB81LQyMxCRtNXmFjsma7gf46MKSv3A,4164
|
|
12
|
+
jcmsuite_notebooks/templates/OptimizationTemplate.m,sha256=TDe0rKi_iLgPxLwv8-YMd_wxb6EEpoaLQfqXJwF4tGo,2360
|
|
13
|
+
jcmsuite_notebooks/templates/ParameterScanTemplate.ipynb.j2,sha256=sq19YE4H7oaLT76ft0fX49jRvuCLaM0xP1c0n1-EDfE,2747
|
|
14
|
+
jcmsuite_notebooks/templates/ParameterScanTemplate.m,sha256=MPnlv-BhOTESq2Wny9-KQCYQEdr-qPVdg7CTtREAJOc,2675
|
|
15
|
+
jcmsuite_notebooks-7.4.2.dist-info/METADATA,sha256=0nMl_Bpw_TON3J0gG4xCYzNPJU_02N9B_bO3Ha3VIBg,2417
|
|
16
|
+
jcmsuite_notebooks-7.4.2.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
|
|
17
|
+
jcmsuite_notebooks-7.4.2.dist-info/RECORD,,
|