Skip to content

API

collimator.dashboard.project

Project

Represents a project in the Collimator dashboard.

Source code in collimator/dashboard/project.py
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
class Project:
    """
    Represents a project in the Collimator dashboard.
    """

    def __init__(
        self,
        summary: ProjectSummary,
        models: dict[str, model_json.Model],
        files: list[str],
        submodels: dict[str, str],
        init_scripts: dict[str, InitScriptVariables] = None,
    ):
        """
        Initialize a new Project instance.

        Args:
            summary (ProjectSummary): The summary of the project.
            models (dict[str, model_json.Model]): A dictionary of models associated with the project.
                The keys are the model names and the values are the json representations of the models.
            files (list[str]): A list of file paths associated with the project.
            submodels (dict[str, str]): A dictionary of submodels associated with the project.
                The keys are the submodel names and the values are the reference IDs of the submodels.
            init_scripts (dict[str, InitScriptVariables], optional): A dictionary of initialization scripts
                associated with the project. Defaults to None.

        """
        self._models = models
        self._submodels = submodels
        self._summary = summary
        self._files = files
        self._init_scripts = init_scripts or {}

    def get_model(self, name: str) -> SimulationContext:
        """
        Retrieves a model from the project.

        Args:
            name (str): The name of the model to retrieve.

        Returns:
            SimulationContext: The simulation context for the retrieved model.

        Raises:
            KeyError: If the specified model name is not found.
        """
        if name not in self._models:
            raise KeyError(f"Model '{name}' not found")

        model = self._models.get(name)
        init_script = None
        if model.configuration.workspace.init_scripts:
            init_script = model.configuration.workspace.init_scripts[0].file_name
        _globals = {}
        if init_script in self._init_scripts:
            _globals = self._init_scripts[init_script].as_dict()

        if model.diagram.nodes:
            logger.info('Loading model "%s"', model.name)
            try:
                return from_model_json.loads_model(model.to_json(), namespace=_globals)
            except BaseException as e:
                logger.error(
                    "Failed to load model %s: %s", model.name, e, exc_info=True
                )

    def create_submodel_instance(
        self,
        name: str,
        instance_name: str,
        instance_parameters: dict[str, Any] = None,
        **kwargs,
    ) -> Diagram:
        """
        Creates an instance of a submodel.

        Args:
            name (str): The name of the submodel.
            instance_name (str): The name of the instance.
            instance_parameters (dict[str, Any], optional): Parameters for the instance. Defaults to None.
            **kwargs: Additional keyword arguments.

        Returns:
            Diagram: The created submodel instance.

        Raises:
            KeyError: If the specified submodel is not found.
            ValueError: If the specified submodel is found but has a None reference ID.
        """
        if name not in self._submodels:
            raise KeyError(
                f"Submodel '{name}' not found. Available submodels: {list(self._submodels.keys())}"
            )
        ref_id = self._submodels.get(name)
        if ref_id is None:
            raise ValueError(f"Submodel '{name}' not found")
        return ReferenceSubdiagram.create_diagram(
            ref_id,
            instance_name,
            instance_parameters=instance_parameters,
            **kwargs,
        )

    def _save_single_submodel(
        self,
        model: model_json.Model,
        submodel_uuid: str = None,
    ):
        project_uuid = self.summary.uuid
        submodel = None
        if submodel_uuid:
            submodel = model_api.get_reference_submodel(project_uuid, submodel_uuid)
        if submodel is None:
            for submodel_name, ref_id in self._submodels.items():
                if ref_id == submodel_uuid:
                    submodel = model_api.get_reference_submodel_by_name(
                        project_uuid, submodel_name
                    )
                    break

        if submodel is None:
            logger.info("Creating submodel '%s' (%s)", model.name, submodel_uuid)
            response = model_api.create_reference_submodel(
                project_uuid,
                model,
                model.parameter_definitions,
                model_uuid=submodel_uuid,
            )
            submodel_uuid = response["uuid"]
            edit_id = response["edit_id"]
        else:
            edit_id = submodel.edit_id
            submodel_uuid = submodel.uuid
            uiprops.copy(submodel, model)
            model.name = submodel.name
            logger.info("Updating submodel '%s' (%s)", model.name, submodel_uuid)
        model_api.update_reference_submodel(
            project_uuid,
            submodel_uuid,
            model,
            edit_id,
            parameter_definitions=model.parameter_definitions,
        )
        return submodel_uuid

    def _save_submodel(self, diagram: Diagram):
        """
        Saves a submodel into the project.

        Args:
            project_uuid (str): The UUID of the project.
            diagram (Diagram): The diagram object representing the submodel.

        Returns:
            None
        """
        model, ref_submodels = to_model_json.convert(diagram)

        for ref_id, ref_submodel in ref_submodels.items():
            self._save_single_submodel(ref_submodel, submodel_uuid=ref_id)

        self._save_single_submodel(model, submodel_uuid=diagram.ref_id)

    def _save_model(
        self,
        diagram: Diagram,
        configuration: model_json.Configuration = None,
    ) -> str:
        """
        Updates or creates a model in the dashboard based on the provided diagram.

        Args:
            project_uuid (str): The UUID of the project to which the model belongs.
            diagram (Diagram): The diagram object representing the model.
            configuration (model_json.Configuration, optional): The configuration object for the model. Defaults to None.

        Returns:
            str: The UUID of the updated or created model.

        Raises:
            None
        """
        project_uuid = self.summary.uuid
        model_json, ref_submodels = to_model_json.convert(
            diagram,
            configuration=configuration,
        )

        for ref_id, ref_submodel in ref_submodels.items():
            self._save_single_submodel(ref_submodel, submodel_uuid=ref_id)

        model_uuid = diagram.ui_id

        model = None
        if model_uuid:
            model = model_api.get_model(model_uuid)

        if model is None:
            model = _get_model_by_name(project_uuid, diagram.name)
            model_uuid = model.uuid if model else None

        if model is None:
            response = model_api.create_model(project_uuid, model_json)
            model_uuid = response["uuid"]
            logger.info("Creating model '%s' (%s)", model_json.name, model_uuid)
        else:
            logger.info("Updating model '%s' (%s)", model_json.name, model_uuid)
            model_json.version = model.version
            uiprops.copy(model, model_json)

        model_api.update_model(model_uuid, model_json)

        return model_uuid

    def save_model(
        self, diagram: Diagram, configuration: model_json.Configuration = None
    ) -> str:
        """
        Save the given diagram as a model. If the diagram already exists, it will be updated.

        Args:
            diagram (Diagram): The diagram to be saved as a model.
            configuration (model_json.Configuration, optional): The configuration for the model. Defaults to None.

        Returns:
            The UUID of the saved model.
        """
        models = {m.name: m for m in self.summary.models}
        if diagram.name in models:
            diagram.ui_id = models[diagram.name].uuid
        return self._save_model(diagram, configuration=configuration)

    def save_submodel(
        self,
        constructor: Callable,
        name: str,
        default_parameters: list[Parameter] = None,
    ) -> str:
        """
        Saves a submodel with the given reference ID and name.

        Args:
            constructor (Callable): The constructor function for the submodel.
            name (str): The name of the submodel.
            default_parameters (list[Parameter], optional): A list of default parameters for the submodel. Defaults to None.

        Returns:
            str: The reference ID of the saved submodel.
        """
        submodel = model_api.get_reference_submodel_by_name(self.summary.uuid, name)
        ref_id = submodel.uuid if submodel else None
        ref_id = ReferenceSubdiagram.register(
            constructor, default_parameters, ref_id=ref_id
        )

        submodel = ReferenceSubdiagram.create_diagram(ref_id, name)
        self._save_submodel(submodel)
        self._submodels[submodel.name] = ref_id
        return ref_id

    @property
    def uuid(self) -> str:
        return self._summary.uuid

    @property
    def summary(self) -> ProjectSummary:
        return self._summary

    @property
    def init_scripts(self) -> dict[str, InitScriptVariables]:
        return self._init_scripts

__init__(summary, models, files, submodels, init_scripts=None)

Initialize a new Project instance.

Parameters:

Name Type Description Default
summary ProjectSummary

The summary of the project.

required
models dict[str, Model]

A dictionary of models associated with the project. The keys are the model names and the values are the json representations of the models.

required
files list[str]

A list of file paths associated with the project.

required
submodels dict[str, str]

A dictionary of submodels associated with the project. The keys are the submodel names and the values are the reference IDs of the submodels.

required
init_scripts dict[str, InitScriptVariables]

A dictionary of initialization scripts associated with the project. Defaults to None.

None
Source code in collimator/dashboard/project.py
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def __init__(
    self,
    summary: ProjectSummary,
    models: dict[str, model_json.Model],
    files: list[str],
    submodels: dict[str, str],
    init_scripts: dict[str, InitScriptVariables] = None,
):
    """
    Initialize a new Project instance.

    Args:
        summary (ProjectSummary): The summary of the project.
        models (dict[str, model_json.Model]): A dictionary of models associated with the project.
            The keys are the model names and the values are the json representations of the models.
        files (list[str]): A list of file paths associated with the project.
        submodels (dict[str, str]): A dictionary of submodels associated with the project.
            The keys are the submodel names and the values are the reference IDs of the submodels.
        init_scripts (dict[str, InitScriptVariables], optional): A dictionary of initialization scripts
            associated with the project. Defaults to None.

    """
    self._models = models
    self._submodels = submodels
    self._summary = summary
    self._files = files
    self._init_scripts = init_scripts or {}

create_submodel_instance(name, instance_name, instance_parameters=None, **kwargs)

Creates an instance of a submodel.

Parameters:

Name Type Description Default
name str

The name of the submodel.

required
instance_name str

The name of the instance.

required
instance_parameters dict[str, Any]

Parameters for the instance. Defaults to None.

None
**kwargs

Additional keyword arguments.

{}

Returns:

Name Type Description
Diagram Diagram

The created submodel instance.

Raises:

Type Description
KeyError

If the specified submodel is not found.

ValueError

If the specified submodel is found but has a None reference ID.

Source code in collimator/dashboard/project.py
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def create_submodel_instance(
    self,
    name: str,
    instance_name: str,
    instance_parameters: dict[str, Any] = None,
    **kwargs,
) -> Diagram:
    """
    Creates an instance of a submodel.

    Args:
        name (str): The name of the submodel.
        instance_name (str): The name of the instance.
        instance_parameters (dict[str, Any], optional): Parameters for the instance. Defaults to None.
        **kwargs: Additional keyword arguments.

    Returns:
        Diagram: The created submodel instance.

    Raises:
        KeyError: If the specified submodel is not found.
        ValueError: If the specified submodel is found but has a None reference ID.
    """
    if name not in self._submodels:
        raise KeyError(
            f"Submodel '{name}' not found. Available submodels: {list(self._submodels.keys())}"
        )
    ref_id = self._submodels.get(name)
    if ref_id is None:
        raise ValueError(f"Submodel '{name}' not found")
    return ReferenceSubdiagram.create_diagram(
        ref_id,
        instance_name,
        instance_parameters=instance_parameters,
        **kwargs,
    )

get_model(name)

Retrieves a model from the project.

Parameters:

Name Type Description Default
name str

The name of the model to retrieve.

required

Returns:

Name Type Description
SimulationContext SimulationContext

The simulation context for the retrieved model.

Raises:

Type Description
KeyError

If the specified model name is not found.

Source code in collimator/dashboard/project.py
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def get_model(self, name: str) -> SimulationContext:
    """
    Retrieves a model from the project.

    Args:
        name (str): The name of the model to retrieve.

    Returns:
        SimulationContext: The simulation context for the retrieved model.

    Raises:
        KeyError: If the specified model name is not found.
    """
    if name not in self._models:
        raise KeyError(f"Model '{name}' not found")

    model = self._models.get(name)
    init_script = None
    if model.configuration.workspace.init_scripts:
        init_script = model.configuration.workspace.init_scripts[0].file_name
    _globals = {}
    if init_script in self._init_scripts:
        _globals = self._init_scripts[init_script].as_dict()

    if model.diagram.nodes:
        logger.info('Loading model "%s"', model.name)
        try:
            return from_model_json.loads_model(model.to_json(), namespace=_globals)
        except BaseException as e:
            logger.error(
                "Failed to load model %s: %s", model.name, e, exc_info=True
            )

save_model(diagram, configuration=None)

Save the given diagram as a model. If the diagram already exists, it will be updated.

Parameters:

Name Type Description Default
diagram Diagram

The diagram to be saved as a model.

required
configuration Configuration

The configuration for the model. Defaults to None.

None

Returns:

Type Description
str

The UUID of the saved model.

Source code in collimator/dashboard/project.py
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
def save_model(
    self, diagram: Diagram, configuration: model_json.Configuration = None
) -> str:
    """
    Save the given diagram as a model. If the diagram already exists, it will be updated.

    Args:
        diagram (Diagram): The diagram to be saved as a model.
        configuration (model_json.Configuration, optional): The configuration for the model. Defaults to None.

    Returns:
        The UUID of the saved model.
    """
    models = {m.name: m for m in self.summary.models}
    if diagram.name in models:
        diagram.ui_id = models[diagram.name].uuid
    return self._save_model(diagram, configuration=configuration)

save_submodel(constructor, name, default_parameters=None)

Saves a submodel with the given reference ID and name.

Parameters:

Name Type Description Default
constructor Callable

The constructor function for the submodel.

required
name str

The name of the submodel.

required
default_parameters list[Parameter]

A list of default parameters for the submodel. Defaults to None.

None

Returns:

Name Type Description
str str

The reference ID of the saved submodel.

Source code in collimator/dashboard/project.py
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
def save_submodel(
    self,
    constructor: Callable,
    name: str,
    default_parameters: list[Parameter] = None,
) -> str:
    """
    Saves a submodel with the given reference ID and name.

    Args:
        constructor (Callable): The constructor function for the submodel.
        name (str): The name of the submodel.
        default_parameters (list[Parameter], optional): A list of default parameters for the submodel. Defaults to None.

    Returns:
        str: The reference ID of the saved submodel.
    """
    submodel = model_api.get_reference_submodel_by_name(self.summary.uuid, name)
    ref_id = submodel.uuid if submodel else None
    ref_id = ReferenceSubdiagram.register(
        constructor, default_parameters, ref_id=ref_id
    )

    submodel = ReferenceSubdiagram.create_diagram(ref_id, name)
    self._save_submodel(submodel)
    self._submodels[submodel.name] = ref_id
    return ref_id

create_project(name)

Creates a new project with the given name.

Parameters:

Name Type Description Default
name str

The name of the project.

required

Returns:

Name Type Description
ProjectSummary Project

The summary of the created project.

Source code in collimator/dashboard/project.py
573
574
575
576
577
578
579
580
581
582
583
584
585
586
def create_project(name: str) -> Project:
    """
    Creates a new project with the given name.

    Args:
        name (str): The name of the project.

    Returns:
        ProjectSummary: The summary of the created project.
    """
    logger.info("Creating project %s...", name)
    response = api.call("/projects", "POST", body={"title": name})
    summary = _parse_project_summary(response)
    return Project(summary=summary, models={}, files=[], submodels={})

delete_project(project_uuid)

Deletes a project with the given UUID.

Parameters:

Name Type Description Default
project_uuid str

The UUID of the project to delete.

required
Source code in collimator/dashboard/project.py
605
606
607
608
609
610
611
612
613
def delete_project(project_uuid: str):
    """
    Deletes a project with the given UUID.

    Args:
        project_uuid (str): The UUID of the project to delete.
    """
    logger.info("Deleting project %s...", project_uuid)
    api.call(f"/projects/{project_uuid}", "DELETE")

get_or_create_project(name)

Retrieves a project by its name or creates a new one if it doesn't exist.

Parameters:

Name Type Description Default
name str

The name of the project.

required

Returns:

Name Type Description
ProjectSummary Project

The summary of the retrieved or created project.

Source code in collimator/dashboard/project.py
589
590
591
592
593
594
595
596
597
598
599
600
601
602
def get_or_create_project(name: str) -> Project:
    """
    Retrieves a project by its name or creates a new one if it doesn't exist.

    Args:
        name (str): The name of the project.

    Returns:
        ProjectSummary: The summary of the retrieved or created project.
    """
    try:
        return get_project_by_name(name)
    except api.CollimatorNotFoundError:
        return create_project(name)

get_project_by_name(project_name)

Retrieves a project by its name.

Parameters:

Name Type Description Default
project_name str

The name of the project to retrieve.

required
project_dir str

The directory where the project is located. If not provided, a temporary directory will be created.

required

Returns:

Name Type Description
Project Project

The project object.

Raises:

Type Description
CollimatorNotFoundError

If the project with the specified name is not found.

CollimatorApiError

If multiple projects with the same name are found.

Source code in collimator/dashboard/project.py
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
def get_project_by_name(project_name: str) -> Project:
    """
    Retrieves a project by its name.

    Args:
        project_name (str): The name of the project to retrieve.
        project_dir (str, optional): The directory where the project is located. If not provided, a temporary directory will be created.

    Returns:
        Project: The project object.

    Raises:
        CollimatorNotFoundError: If the project with the specified name is not found.
        CollimatorApiError: If multiple projects with the same name are found.

    """

    response = api.get("/projects")
    results = []
    for project in response["projects"]:
        if project["title"] == project_name:
            results.append(project)

    user_profile = api.get("/user/profile")

    if len(results) == 0:
        raise api.CollimatorNotFoundError(f"Project '{project_name}' not found")
    elif len(results) > 1:
        uuids = []
        for p in results:
            if p["is_default"]:
                uuids.append(f"- {p['uuid']} (public project)")
            elif p["owner_uuid"] == user_profile["uuid"]:
                uuids.append(f"- {p['uuid']} (private project)")
            else:
                uuids.append(f"- {p['uuid']} (shared with me)")
        uuids = "\n".join(uuids)

        raise api.CollimatorApiError(
            f"Multiple projects found with name '{project_name}':\n{uuids}\n"
            "Please use get_project_by_uuid() instead."
        )

    project_uuid = results[0]["uuid"]
    return get_project_by_uuid(project_uuid)

get_project_by_uuid(project_uuid)

Retrieves a project with the given UUID and downloads its files.

Parameters:

Name Type Description Default
project_uuid str

The UUID of the project to retrieve.

required

Returns:

Name Type Description
Project Project

The downloaded project, including its models and files.

Source code in collimator/dashboard/project.py
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
def get_project_by_uuid(project_uuid: str) -> Project:
    """
    Retrieves a project with the given UUID and downloads its files.

    Args:
        project_uuid (str): The UUID of the project to retrieve.

    Returns:
        Project: The downloaded project, including its models and files.
    """

    logger.info("Downloading project %s...", project_uuid)

    project_response = api.get(f"/projects/{project_uuid}")
    project_summary = _parse_project_summary(project_response)

    # download project files
    files = []

    project_dir = os.getcwd()
    logger.info("Project dir: %s", project_dir)

    for file in project_summary.files:
        if file.status == "processing_completed":
            dst = os.path.join(project_dir, file.name)
            _download_file(file, project_uuid, dst)
            files.append(dst)
        else:
            logger.warning(
                "File %s is not ready to be downloaded (status: %s)",
                file.name,
                file.status,
            )

    # Must first register submodels
    submodels_response = api.get(f"/project/{project_uuid}/submodels")
    visited = set()
    ref_submodels: dict[str, model_json.Model] = {}
    submodels = {}

    for model_summary in submodels_response["submodels"]:
        submodel = model_api.get_reference_submodel(project_uuid, model_summary["uuid"])
        if submodel is None:
            logger.warning(
                "Could not find submodel %s (%s)",
                model_summary["name"],
                model_summary["uuid"],
            )
            continue
        ref_submodels.update(
            {
                model_summary["uuid"]: submodel,
                **_get_reference_submodels(project_uuid, submodel, visited),
            }
        )
    for model_summary in project_summary.models:
        model = model_api.get_model(model_summary.uuid)
        if model is None:
            logger.warning(
                "Could not find model %s (%s)", model_summary.name, model_summary.uuid
            )
            continue
        ref_submodels.update(_get_reference_submodels(project_uuid, model, visited))
    for submodel_uuid, submodel in ref_submodels.items():
        logger.info("Registering submodel %s", submodel.name)
        from_model_json.register_reference_submodel(submodel_uuid, submodel)
        submodels[submodel.name] = submodel_uuid

    # Load models
    models = {}
    init_scripts_vars = {}
    for model_summary in project_summary.models:
        if model_summary.kind == ModelKind.MODEL:
            model = model_api.get_model(model_summary.uuid)
            init_scripts = model.configuration.workspace.init_scripts
            if len(init_scripts) > 1:
                raise NotImplementedError("Only one init script is supported")
            elif len(init_scripts) == 1 and init_scripts[0]:
                filename = init_scripts[0].file_name
                init_script_path = os.path.join(project_dir, filename)
                if os.path.exists(init_script_path):
                    logger.info("Evaluating %s", init_scripts[0])
                    with open(init_script_path, "r") as f:
                        import numpy as np

                        _globals = {**globals(), "np": np}
                        exec(f.read(), _globals)
                        init_scripts_vars[filename] = InitScriptVariables(_globals)

            models[model_summary.name] = model

    return Project(
        summary=project_summary,
        models=models,
        files=files,
        submodels=submodels,
        init_scripts=init_scripts_vars,
    )

simulate(model_uuid, timeout=None, ignore_cache=False, parameters=None) async

Runs a simulation for the specified model UUID.

Parameters:

Name Type Description Default
model_uuid str

The UUID of the model to run the simulation for.

required
timeout int

The maximum time to wait for the simulation to complete, in seconds. Defaults to None.

None

Returns:

Name Type Description
SimulationResults SimulationResults

The results of the simulation.

Raises:

Type Description
TimeoutError

If the simulation does not complete within the specified timeout.

SimulationFailedError

If the simulation fails.

Source code in collimator/dashboard/project.py
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
async def simulate(
    model_uuid: str,
    timeout: int = None,
    ignore_cache: bool = False,
    parameters: list[Parameter] = None,
) -> SimulationResults:
    """
    Runs a simulation for the specified model UUID.

    Args:
        model_uuid (str): The UUID of the model to run the simulation for.
        timeout (int, optional): The maximum time to wait for the simulation to complete, in seconds. Defaults to None.

    Returns:
        SimulationResults: The results of the simulation.

    Raises:
        TimeoutError: If the simulation does not complete within the specified timeout.
        SimulationFailedError: If the simulation fails.

    """
    start_time = time.perf_counter()
    body = {"ignore_cache": ignore_cache}
    if parameters:
        body["parameters"] = {}
        for p in parameters:
            if p.name is None:
                raise ValueError("Parameter name cannot be None")
            json_param = model_json.Parameter(
                value=p.value_as_str(), is_string=isinstance(p.value, str))
            body["parameters"][p.name] = json_param.to_dict()

    summary = api.post(f"/models/{model_uuid}/simulations", body=body)

    # wait for simulation completion
    while summary["status"] not in ("completed", "failed"):
        await asyncio.sleep(1)
        logger.info("Waiting for simulation to complete...")
        summary = api.get(f"/models/{model_uuid}/simulations/{summary['uuid']}")
        if timeout is not None and time.perf_counter() - start_time > timeout:
            stop_simulation(model_uuid, summary["uuid"])
            raise TimeoutError

    logs = api.get(f"/models/{model_uuid}/simulations/{summary['uuid']}/logs")
    logger.info(logs)

    if summary["status"] == "failed":
        raise SimulationFailedError(summary["fail_reason"])

    signals = results.get_signals(model_uuid, summary["uuid"])

    return SimulationResults(
        context=None,
        time=signals["time"],
        outputs=signals,
    )

stop_simulation(model_uuid, simulation_uuid)

Stops a running simulation.

Parameters:

Name Type Description Default
model_uuid str

The UUID of the model for which the simulation is running.

required
simulation_uuid str

The UUID of the simulation to stop.

required

Returns:

Name Type Description
dict dict

The response from the API call.

Source code in collimator/dashboard/project.py
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
def stop_simulation(model_uuid: str, simulation_uuid: str) -> dict:
    """
    Stops a running simulation.

    Args:
        model_uuid (str): The UUID of the model for which the simulation is running.
        simulation_uuid (str): The UUID of the simulation to stop.

    Returns:
        dict: The response from the API call.

    """
    return api.post(
        f"/models/{model_uuid}/simulations/{simulation_uuid}/events",
        body={"command": "stop"},
    )

upload_file(project_uuid, name, fp, overwrite=True)

Uploads a file to a project.

Parameters:

Name Type Description Default
project_uuid str

The UUID of the project.

required
name str

The name of the file.

required
fp IO[AnyStr]

The file pointer of the file to be uploaded.

required
overwrite bool

Flag indicating whether to overwrite an existing file with the same name. Defaults to True.

True

Returns:

Name Type Description
dict

A dictionary containing the summary of the uploaded file.

Raises:

Type Description
CollimatorApiError

If the file upload fails.

Source code in collimator/dashboard/project.py
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
def upload_file(project_uuid: str, name: str, fp: IO[AnyStr], overwrite=True):
    """
    Uploads a file to a project.

    Args:
        project_uuid (str): The UUID of the project.
        name (str): The name of the file.
        fp (IO[AnyStr]): The file pointer of the file to be uploaded.
        overwrite (bool, optional): Flag indicating whether to overwrite an existing file with the same name.
            Defaults to True.

    Returns:
        dict: A dictionary containing the summary of the uploaded file.

    Raises:
        api.CollimatorApiError: If the file upload fails.
    """

    mime_type, _ = mimetypes.guess_type(name)
    size = os.fstat(fp.fileno()).st_size

    logger.info(
        "Uploading file %s (type: %s, size: %d) to project %s...",
        name,
        mime_type,
        size,
        project_uuid,
    )
    body = {
        "name": name,
        "content_type": mime_type,
        "overwrite": overwrite,
        "size": size,
    }
    put_url_response = api.call(f"/projects/{project_uuid}/files", "POST", body=body)
    s3_presigned_url = put_url_response["put_presigned_url"]
    s3_response = requests.put(
        s3_presigned_url,
        headers={"Content-Type": mime_type},
        data=fp,
        verify=False,
    )
    if s3_response.status_code != 200:
        logging.error("s3 upload failed: %s", s3_response.text)
        raise api.CollimatorApiError(
            f"Failed to upload file {name} to project {project_uuid}"
        )
    file_uuid = put_url_response["summary"]["uuid"]
    process_response = api.call(
        f"/projects/{project_uuid}/files/{file_uuid}/process", "POST"
    )
    return process_response["summary"]

upload_files(project_uuid, files, overwrite=True)

Uploads multiple files to a project.

Parameters:

Name Type Description Default
project_uuid str

The UUID of the project.

required
files list[str]

A list of file paths to be uploaded.

required
overwrite bool

Flag indicating whether to overwrite existing files. Defaults to True.

True
Source code in collimator/dashboard/project.py
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
def upload_files(project_uuid: str, files: list[str], overwrite=True):
    """
    Uploads multiple files to a project.

    Args:
        project_uuid (str): The UUID of the project.
        files (list[str]): A list of file paths to be uploaded.
        overwrite (bool, optional): Flag indicating whether to overwrite existing files.
            Defaults to True.
    """
    with concurrent.futures.ThreadPoolExecutor() as executor:
        futures = []
        for file in files:
            with open(file, "rb") as fp:
                futures.append(
                    executor.submit(
                        upload_file, project_uuid, os.path.basename(file), fp, overwrite
                    )
                )
        for future in concurrent.futures.as_completed(futures):
            future.result()