"""Provides the wrapper for Comsol model objects."""
from __future__ import annotations
from .node import Node
from numpy import array, ndarray
from numpy import integer
from pathlib import Path
from re import match
from logging import getLogger
from jpype import JClass
from typing import overload, Literal
from collections.abc import Iterator
from numpy.typing import ArrayLike, NDArray
from numpy import int32, float64
# The following look-up table is used by the `modules()` method. It maps the
# product names (add-on modules) returned by `model.getUsedProducts()` to the
# same sanitized names used in the look-up table in the `clients` module. So it
# essentially drops the Unicode trademark symbols as well as the redundant
# "Module". The strings returned by `getUsedProducts()` seem to correspond
# exactly to the product names in the left column of the table on page 42 of
# Comsol 6.3's Programming Reference Manual.
modules = {
'AC/DC Module': 'AC/DC',
'Acoustics Module': 'Acoustics',
'Battery Design Module': 'Battery Design',
'CAD Import Module': 'CAD Import',
'CFD Module': 'CFD',
'COMSOL Multiphysics': 'Comsol core',
'Chemical Reaction Engineering Module': 'Chemical Reaction Engineering',
'Cluster Computing Module': 'Cluster Computing',
'Cluster computing functionality': 'Cluster Computing',
'Composite Materials Module': 'Composite Materials',
'Corrosion Module': 'Corrosion',
'Design Module': 'Design',
'ECAD Import Module': 'ECAD Import',
'Electric Discharge Module': 'Electric Discharge',
'Electrochemistry Module': 'Electrochemistry',
'Electrodeposition Module': 'Electrodeposition',
'Fatigue Module': 'Fatigue',
'File Import for CATIA V5': 'File Import for Catia v5',
'Fuel Cell & Electrolyzer Module': 'Fuel Cell & Electrolyzer',
'Geomechanics Module': 'Geomechanics',
'Heat Transfer Module': 'Heat Transfer',
'Liquid & Gas Properties Module': 'Liquid & Gas Properties',
'LiveLink™ for AutoCAD®': 'LiveLink AutoCAD',
'LiveLink™ for PTC® Creo® Parametric™': 'LiveLink PTC Creo Parametric',
'LiveLink™ for Excel®': 'LiveLink Excel',
'LiveLink™ for Inventor®': 'LiveLink Inventor',
'LiveLink™ for MATLAB®': 'LiveLink Matlab',
'LiveLink™ for Revit®': 'LiveLink Revit',
'LiveLink™ for PTC® Pro/ENGINEER®': 'LiveLink PTC Pro/ENGINEER',
'LiveLink™ for Solid Edge®': 'LiveLink Solid Edge',
'LiveLink™ for SOLIDWORKS®': 'LiveLink SolidWorks',
'MEMS Module': 'MEMS',
'Microfluidics Module': 'Microfluidics',
'Mixer Module': 'Mixer',
'Molecular Flow Module': 'Molecular Flow',
'Multibody Dynamics Module': 'Multibody Dynamics',
'Nonlinear Structural Materials Module': 'Nonlinear Structural Materials',
'Optimization Module': 'Optimization',
'Particle Tracing Module': 'Particle Tracing',
'Pipe Flow Module': 'Pipe Flow',
'Plasma Module': 'Plasma',
'Polymer Flow Module': 'Polymer Flow',
'Ray Optics Module': 'Ray Optics',
'RF Module': 'RF',
'Rotordynamics Module': 'Rotordynamics',
'Semiconductor Module': 'Semiconductor',
'Structural Mechanics Module': 'Structural Mechanics',
'Subsurface Flow Module': 'Subsurface Flow',
'Uncertainty Quantification Module': 'Uncertainty Quantification',
'Wave Optics Module': 'Wave Optics',
}
log = getLogger(__package__)
[docs]
class Model:
"""
Represents a Comsol model.
The class is not intended to be instantiated directly. Rather, the model
would be loaded from a file by the [client](#Client).
Example usage:
```python
import mph
client = mph.start()
model = client.load('capacitor.mph')
model.parameter('U', '1 [V]')
model.parameter('d', '1 [mm]')
model.solve()
C = model.evaluate('2*es.intWe/U^2', 'pF')
print(f'capacitance C = {C:.3f} pF')
```
The focus of the functionality exposed by this class is to inspect an
existing model, possibly change parameters, solve the model, then evaluate
the results. The intention is not *per se* to create the model from scratch
or to extensively modify its structure, though some such functionality is
offered here, and even more of it through the [`Node`](#Node) class.
This class is a wrapper around the [`com.comsol.model.Model`][1] Java
class, which itself is wrapped by JPype and can be accessed directly via
the `.java` attribute. The full Comsol functionality is thus available if
needed.
The `parent` argument to the constructor is usually that internal Java
object. But in order to simplify extending the class with custom
functionality, the constructor also accepts instances of this very class
or a child class. In that case, it will preserve the original `.java`
reference throughout the class hierarchy so that it is possible to
"type-cast" an existing `Model` instance (as loaded by the client) to a
derived child class.
[1]: https://doc.comsol.com/6.0/doc/com.comsol.help.comsol/api\
/com/comsol/model/Model.html
"""
java: JClass
"""Java object that this instance is wrapped around."""
############
# Internal #
############
def __init__(self, parent: JClass | Model):
if isinstance(parent, Model):
java = parent.java
else:
java = parent
self.java = java
def __str__(self) -> str:
return self.name()
def __repr__(self) -> str:
return f"{self.__class__.__name__}('{self}')"
def __eq__(self, other: object) -> bool:
if not isinstance(other, Model):
return NotImplemented
return (self.java.tag() == other.java.tag())
def __truediv__(self, other: str | Node | None) -> Node:
if isinstance(other, str):
return Node(self, other)
if isinstance(other, Node):
return Node(self, str(other))
if other is None:
return Node(self, None)
return NotImplemented
def __contains__(self, node: str | Node) -> bool:
return (isinstance(node, (str, Node)) and (self/node).exists())
def __iter__(self) -> Iterator[Node]:
yield from (self/None).children()
##############
# Inspection #
##############
[docs]
def name(self) -> str:
"""Returns the model's name."""
name = str(self.java.label())
if name.endswith('.mph'):
name = name.rsplit('.', maxsplit=1)[0]
return name
[docs]
def file(self) -> Path:
"""Returns the absolute path to the file the model was loaded from."""
return Path(str(self.java.getFilePath())).resolve()
[docs]
def version(self) -> str:
"""Returns the Comsol version the model was last saved with."""
version = str(self.java.getComsolVersion())
return match(r'(?i)Comsol.+?(\d[0-9.a-z]*)', version).group(1)
[docs]
def functions(self) -> list[str]:
"""Returns the names of all globally defined functions."""
return [child.name() for child in self/'functions']
[docs]
def components(self) -> list[str]:
"""Returns the names of all model components."""
return [child.name() for child in self/'components']
[docs]
def geometries(self) -> list[str]:
"""Returns the names of all geometry sequences."""
return [child.name() for child in self/'geometries']
[docs]
def selections(self) -> list[str]:
"""Returns the names of all selections."""
return [child.name() for child in self/'selections']
[docs]
def physics(self) -> list[str]:
"""Returns the names of all physics interfaces."""
return [child.name() for child in self/'physics']
[docs]
def multiphysics(self) -> list[str]:
"""Returns the names of all multiphysics interfaces."""
return [child.name() for child in self/'multiphysics']
[docs]
def materials(self) -> list[str]:
"""Returns the names of all materials."""
return [child.name() for child in self/'materials']
[docs]
def meshes(self) -> list[str]:
"""Returns the names of all mesh sequences."""
return [child.name() for child in self/'meshes']
[docs]
def studies(self) -> list[str]:
"""Returns the names of all studies."""
return [child.name() for child in self/'studies']
[docs]
def solutions(self) -> list[str]:
"""Returns the names of all solutions."""
return [child.name() for child in self/'solutions']
[docs]
def datasets(self) -> list[str]:
"""Returns the names of all datasets."""
return [child.name() for child in self/'datasets']
[docs]
def plots(self) -> list[str]:
"""Returns the names of all plots."""
return [child.name() for child in self/'plots']
[docs]
def exports(self) -> list[str]:
"""Returns the names of all exports."""
return [child.name() for child in self/'exports']
[docs]
def modules(self) -> list[str]:
"""Returns the names of modules/products required to be licensed."""
return [
modules.get(key, str(key)) for key in self.java.getUsedProducts()
]
[docs]
def problems(self) -> list[dict[str, str | Node]]:
"""
Returns problems reported by nodes in the model.
This method lets users check if any problems are reported throughout
the model by testing `if model.problems():` in application code, to
then act accordingly. See [`Node.problems()`](#Node.problems) on how
problems (error/warning messages and their origin) are returned.
"""
return (self/None).problems()
###########
# Solving #
###########
[docs]
def build(self, geometry: str | Node = None):
"""Builds the named geometry, or all of them if none given."""
geometries = self/'geometries'
if geometry is None:
if not geometries.children():
error = 'No geometry sequence defined in the model.'
log.error(error)
raise RuntimeError(error)
elif isinstance(geometry, str):
geometry = geometries/geometry
elif isinstance(geometry, Node):
if geometry.parent() != self/'geometries':
error = f'Node "{geometry}" is not a geometry node.'
log.error(error)
raise ValueError(error)
else:
error = f'Geometry {geometry!r} is neither string nor node.'
log.error(error)
raise TypeError(error)
if geometry and not geometry.exists():
error = f'Geometry sequence "{geometry.name()}" does not exist.'
log.error(error)
raise LookupError(error)
nodes = [geometry] if geometry else geometries.children()
for node in nodes:
log.info(f'Running geometry sequence "{node.name()}".')
node.run()
log.info('Finished geometry sequence.')
[docs]
def mesh(self, mesh: str | Node = None):
"""Runs the named mesh sequence, or all of them if none given."""
meshes = self/'meshes'
if mesh is None:
if not meshes.children():
error = 'No mesh sequences defined in the model.'
log.error(error)
raise RuntimeError(error)
elif isinstance(mesh, str):
mesh = meshes/mesh
elif isinstance(mesh, Node):
if mesh.parent() != self/'meshes':
error = f'Node "{mesh}" is not a mesh node.'
log.error(error)
raise ValueError(error)
else:
error = f'Mesh {mesh!r} is neither string nor node.'
log.error(error)
raise TypeError(error)
if mesh and not mesh.exists():
error = f'Mesh sequence "{mesh.name()}" does not exist.'
log.error(error)
raise LookupError(error)
nodes = [mesh] if mesh else meshes.children()
for node in nodes:
log.info(f'Running mesh sequence "{node.name()}".')
node.run()
log.info('Finished mesh sequence.')
[docs]
def solve(self, study: str | Node = None):
"""Solves the named study, or all of them if none given."""
studies = self/'studies'
if study is None:
if not studies.children():
error = 'No studies defined in the model.'
log.error(error)
raise RuntimeError(error)
elif isinstance(study, str):
study = studies/study
elif isinstance(study, Node):
if study.parent() != self/'studies':
error = f'Node "{study}" is not a study node.'
log.error(error)
raise ValueError(error)
else:
error = f'Study {study!r} is neither string nor node.'
log.error(error)
raise TypeError(error)
if study and not study.exists():
error = f'Study "{study.name()}" does not exist.'
log.error(error)
raise LookupError(error)
nodes = [study] if study else studies.children()
for node in nodes:
log.info(f'Running study "{node.name()}".')
node.run()
log.info('Finished solving study.')
##############
# Evaluation #
##############
[docs]
def inner(self,
dataset: str | Node = None,
) -> tuple[NDArray[int32], NDArray[float64]]:
"""
Returns the indices and values of inner solutions.
These are the solution indices and time values in time-dependent
studies, returned as a tuple of an integer array and a floating-point
array. A `dataset` name may be specified. Otherwise the default dataset
is used.
"""
# Validate dataset argument.
if dataset is not None:
if isinstance(dataset, str):
dataset = self/'datasets'/dataset
if not isinstance(dataset, Node):
error = 'Dataset must be a dataset name or dataset node.'
log.error(error)
raise TypeError(error)
if not dataset.exists():
error = f'Dataset "{dataset.name()}" does not exist.'
log.error(error)
raise ValueError(error)
# Find corresponding solution.
if 'solution' in dataset.properties():
tag = dataset.property('solution')
elif 'data' in dataset.properties():
tag = dataset.property('data')
for solution in self/'solutions':
if solution.tag() == tag:
break
else:
error = f'Dataset "{dataset.name()}" does not refer to a solution.'
log.error(error)
raise RuntimeError(error)
# Get indices from solution info and values from solution itself.
java = solution.java
info = java.getSolutioninfo()
indices = array(info.getSolnum(1, True))
values = array(java.getPVals())
return (indices, values)
[docs]
def outer(self,
dataset: str | Node = None,
) -> tuple[NDArray[int32], NDArray[float64]]:
"""
Returns the indices and values of outer solutions.
These are the solution indices and values in parametric sweeps,
returned as a tuple of an integer array and a floating-point array. A
`dataset` name may be specified. Otherwise the default dataset is used.
"""
# Validate dataset argument.
if dataset is not None:
if isinstance(dataset, str):
dataset = self/'datasets'/dataset
if not isinstance(dataset, Node):
error = 'Dataset must be a dataset name or dataset node.'
log.error(error)
raise TypeError(error)
if not dataset.exists():
error = f'Dataset "{dataset.name()}" does not exist.'
log.error(error)
raise ValueError(error)
# Find corresponding solution.
if 'solution' in dataset.properties():
tag = dataset.property('solution')
elif 'data' in dataset.properties():
tag = dataset.property('data')
for solution in self/'solutions':
if solution.tag() == tag:
break
else:
error = f'Dataset "{dataset.name()}" does not refer to a solution.'
log.error(error)
raise RuntimeError(error)
# Get indices and values from solution info.
info = solution.java.getSolutioninfo()
indices = array(info.getOuterSolnum())
values = array([info.getPvals([[index,1]])[0][0] for index in indices])
return (indices, values)
[docs]
def evaluate(self,
expression: str | list[str],
unit: str | list[str] = None,
dataset: str | Node = None,
inner: Literal['first', 'last']
| list[int] | NDArray[integer] = None,
outer: int | integer = None,
) -> NDArray[float64] | list[NDArray[float64]]:
"""
Evaluates an expression and returns the numerical results.
The `expression` may be a string, denoting a single expression, or a
sequence of strings, denoting multiple. The optional `unit` must be
given correspondingly. If omitted, default units are used. The
expression may be a global one, or a scalar field, or particle data.
Results are returned as (lists of) [NumPy arrays](#ndarray), of
whichever dimensionality they may then have.
A `dataset` may be specified, but it must be a solution dataset.
Derived datasets are not supported. If no dataset is given, the
expression will be evaluated on the default dataset. If the solution
stored in the dataset is time-dependent, one or several `inner`
solutions can be preselected, either by an index number, a sequence of
indices, or by passing `'first`'/`'last'` to select the very
first/last index. If the dataset represents a parameter sweep, the
`outer` solution(s) can be selected by index or sequence of indices.
With the help of appropriately defined operators in the model, this
method here should be able to query any and all data. If you don't
find that to be the case, consider using the Comsol API directly via
the `.java` attribute of this class, and refer to the "Results" chapter
in the Comsol Programming Manual for guidance.
"""
# Validate input arguments.
if dataset is not None:
if isinstance(dataset, str):
dataset = self/'datasets'/dataset
if not isinstance(dataset, Node):
error = 'Dataset must be a dataset name or dataset node.'
log.error(error)
raise TypeError(error)
if not (inner is None
or (isinstance(inner, str) and inner in ('first', 'last'))
or (isinstance(inner, list)
and all(isinstance(index, int) for index in inner))
or (isinstance(inner, ndarray) and inner.dtype.kind == 'i')):
error = ('Argument "inner", if specified, must be either '
'"first", "last", or a list/array of integers.')
log.error(error)
raise TypeError(error)
if outer is not None and not isinstance(outer, (int, integer)):
error = 'Argument "outer", if specified, must be an integer index.'
log.error(error)
raise TypeError(error)
# Find the default dataset if nothing specified.
if not dataset:
eval = (self/'evaluations').create('Eval')
tag = eval.property('data')
eval.remove()
for dataset in self/'datasets':
if dataset.tag() == tag:
break
else:
error = 'Could not determine default dataset.'
log.error(error)
raise RuntimeError(error)
if not dataset.exists():
error = f'Dataset "{dataset.name()}" does not exist.'
log.error(error)
raise ValueError(error)
log.info(f'Evaluating "{expression}" on dataset "{dataset.name()}".')
# Find corresponding solution.
if 'solution' in dataset.properties():
tag = dataset.property('solution')
elif 'data' in dataset.properties():
tag = dataset.property('data')
for solution in self/'solutions':
if solution.tag() == tag:
break
else:
error = f'Dataset "{dataset.name()}" does not refer to a solution.'
log.error(error)
raise RuntimeError(error)
# Make sure solution has actually been computed.
if solution.java.isEmpty():
error = 'The solution has not been computed.'
log.error(error)
raise RuntimeError(error)
# Try to perform a global evaluation, which may fail.
eval = (self/'evaluations').create('EvalGlobal')
eval.property('expr', expression)
if unit:
eval.property('unit', unit)
eval.property('data', dataset)
if outer is not None:
eval.property('outersolnum', outer)
try:
log.debug('Trying global evaluation.')
java = eval.java
results = array(java.computeResult())
if java.isComplex():
results = results[0].astype('complex') + 1j*results[1]
else:
results = results[0]
log.info('Finished global evaluation.')
if inner is None:
pass
elif inner == 'first':
results = results[0]
elif inner == 'last':
results = results[-1]
else:
if isinstance(inner, list):
inner = array(inner)
results = results[inner-1]
return results.squeeze()
# Move on if this fails. Seems to not be a global expression then.
except Exception:
log.debug('Global evaluation failed. Moving on.')
finally:
eval.remove()
# For particle datasets, create an "EvalPoint" feature.
if dataset.type() == 'Particle':
eval = (self/'evaluations').create('EvalPoint')
if inner in ('first', 'last'):
eval.property('innerinput', inner)
elif inner is not None:
eval.property('innerinput', 'manual')
eval.property('solnum', inner)
# Otherwise create an "Eval" feature.
else:
eval = (self/'evaluations').create('Eval')
# Set up the evaluation feature.
eval.property('expr', expression)
if unit:
eval.property('unit', unit)
eval.property('data', dataset)
if outer is not None:
eval.property('outersolnum', outer)
# Retrieve the data.
log.info('Retrieving data.')
java = eval.java
if dataset.type() == 'Particle':
results = array(java.getReal())
if java.isComplex():
results = results.astype('complex')
results += 1j * array(java.getImag())
if isinstance(expression, (tuple, list)):
shape = results.shape[1:]
results = results.reshape(len(expression), -1, *shape)
else:
results = array(java.getData())
if java.isComplex():
results = results.astype('complex')
results += 1j * array(java.getImagData())
if inner == 'first':
results = results[:, 0, :]
elif inner == 'last':
results = results[:, -1, :]
elif inner is not None:
if isinstance(inner, list):
inner = array(inner)
results = results[:, inner-1, :]
log.info('Finished retrieving data.')
# Remove the temporary evaluation feature we added to the model.
eval.remove()
# Squeeze out singleton array dimensions.
if isinstance(expression, (list, tuple)):
results = [result.squeeze() for result in results]
else:
results = results.squeeze()
# Return array of results.
return results
###############
# Interaction #
###############
[docs]
def rename(self, name: str):
"""Assigns a new name to the model."""
self.java.label(name)
@overload
def parameter(self,
name: str,
value: str | int | float | complex,
*,
evaluate: Literal[False],
): ...
@overload
def parameter(self,
name: str,
value: Literal[None],
*,
evaluate: Literal[False],
) -> str: ...
@overload
def parameter(self,
name: str,
value: Literal[None],
*,
evaluate: Literal[True],
) -> int | float | complex: ...
[docs]
def parameter(
self, name, value=None, *, evaluate=False
):
"""
Returns or sets the parameter of the given name.
Returns the value of parameter `name` if no `value` is given. Otherwise
sets the value.
Values are accepted as expressions (strings, possibly including the
unit inside square brackets) or as numerical values (referring to
default units).
By default, values are returned as strings, i.e. the expression as
entered in the user interface. That expression may include the unit,
again inside brackets. If the option `evaluate` is set to `True`, the
numerical value that the expression evaluates to is returned.
"""
if value is None:
if not evaluate:
try:
return str(self.java.param().get(name))
except Exception:
error = f'Parameter "{name}" is not defined.'
log.error(error)
raise ValueError(error) from None
else:
try:
return self.java.param().evaluate(name)
except Exception:
try:
value = self.java.param().evaluateComplex(name)
return complex(value[0], value[1])
except Exception:
error = f'Evaluation of parameter "{name}" failed.'
log.error(error)
raise RuntimeError(error) from None
else:
if isinstance(value, complex):
value = str(value)
self.java.param().set(name, value)
@overload
def parameters(self,
evaluate: Literal[True],
) -> dict[str, str | int | float | complex]: ...
@overload
def parameters(self, evaluate: Literal[False]) -> dict[str, str]: ...
[docs]
def parameters(self, evaluate=False):
"""
Returns the global model parameters.
The parameters are returned as a dictionary indexed by the parameter
names and mapping to the parameter values.
Value are returned as string expressions, i.e. as entered by the user,
unless `evaluate` is set to `True`, in which case the expressions are
evaluated and the corresponding numbers are returned.
"""
if not evaluate:
return {str(name): str(self.java.param().get(name))
for name in self.java.param().varnames()}
else:
return {str(name): self.java.param().evaluate(name)
for name in self.java.param().varnames()}
@overload
def description(self, name: str, text: str) -> None: ...
@overload
def description(self, name: str, text: None) -> str: ...
[docs]
def description(self, name, text=None):
"""
Returns or sets the description of the named parameter.
If no `text` is given, returns the text description of parameter
`name`. Otherwise sets it.
"""
if text is not None:
value = self.parameter(name)
self.java.param().set(name, value, text)
else:
return str(self.java.param().descr(name))
[docs]
def descriptions(self) -> dict[str, str]:
"""Returns all parameter descriptions as a dictionary."""
return {name: self.description(name) for name in self.parameters()}
@overload
def property(self,
node: Node | str,
name: str,
value: Node | bool | float | str | Path | ArrayLike,
): ...
@overload
def property(self,
node: Node | str,
name: str,
value: None,
) -> Node | bool | float | str | Path | ArrayLike: ...
[docs]
def property(self, node, name, value = None):
"""
Returns or changes the value of the named node property.
If no `value` is given, returns the value of property `name`. Otherwise
sets the property to the given value.
"""
return (self/node).property(name, value)
[docs]
def properties(
self,
node: Node | str,
) -> dict[
str,
Node | bool | float | str | Path
| list[str] | list[list[str]] | NDArray
| None
]:
"""Returns names and values of all node properties as a dictionary."""
return (self/node).properties()
[docs]
def create(self, node: Node | str, *arguments: str) -> Node:
"""
Creates a new feature node.
Note that this only works for what Comsol considers model "features",
not for any and all nodes in the model tree (such as property groups of
materials).
If the given `node` does not exist, creates a node with its name in the
node's parent group. Otherwise creates a child node underneath the
given node and assigns it an automatically generated unique name/label.
Refer to the Comsol documentation for valid `arguments`. It is often
just the feature type of the child node to be created, given as a
string such as "Block", but may also require different or more
arguments.
Returns the newly created child node as a `Node` instance.
"""
node = self/node
if node.exists():
return node.create(*arguments)
else:
return node.parent().create(*arguments, name=node.name())
[docs]
def remove(self, node: Node | str):
"""Removes the node from the model tree."""
(self/node).remove()
#########
# Files #
#########
[docs]
def import_(self, node: Node | str, file: Path | str):
"""
Imports external data from a file and assigns it to the node.
Note the trailing underscore in the method name. It is needed so that
the Python parser does not treat the name as an `import` statement.
"""
if isinstance(node, str):
node = self/node
if not node.exists():
error = f'Node "{node}" does not exist in model tree.'
log.error(error)
raise LookupError(error)
node.import_(file)
[docs]
def export(self, node: Node | str | None = None, file: Path | str = None):
"""
Runs the export node, either given by name or node reference.
A `file` name can be specified. Otherwise the file name defined in the
node's properties will be used. If called without any arguments, all
export nodes defined in the model are run using the default file names.
"""
if node is None:
for node in self/'exports':
log.info(f'Running export node "{node.name()}".')
node.run()
log.info('Finished running export.')
return
if isinstance(node, str):
node = self/'exports'/node
if not node.exists():
error = f'Node "{node}" does not exist in model tree.'
log.error(error)
raise ValueError(error)
if file:
file = Path(file)
type = node.type()
if type in ('Image', 'Data', 'Mesh', 'Table', 'Plot',
'Touchstone'):
node.property('filename', str(file))
elif type == 'Animation':
if file.suffix == '.gif':
node.property('type', 'movie')
node.property('movietype', 'gif')
node.property('giffilename', str(file))
elif file.suffix == '.swf':
# Flash format no longer supported as of Comsol 6.1.
node.property('type', 'movie')
node.property('movietype', 'flash')
node.property('flashfilename', str(file))
elif file.suffix == '.avi':
node.property('type', 'movie')
node.property('movietype', 'avi')
node.property('avifilename', str(file))
elif file.suffix == '.webm':
node.property('type', 'movie')
node.property('movietype', 'webm')
node.property('webmfilename', str(file))
elif file.suffix == '.png':
node.property('type', 'imageseq')
node.property('imagefilename', str(file))
else:
error = ('Cannot deduce animation type from file ending '
f'"{file.suffix}" . Should be one of: .gif, .swf, '
f'.avi, .webm, or .png.')
log.error(error)
raise ValueError(error)
else:
error = f'Node "{node}" is of unexpected type "{type}".'
log.error(error)
raise TypeError(error)
log.info(f'Running export node "{node.name()}".')
node.run()
log.info('Finished running export.')
[docs]
def clear(self):
"""Clears stored solution, mesh, and plot data."""
log.info('Clearing stored plot data.')
(self/'plots').java.clearStoredPlotData()
log.info('Finished clearing plots.')
log.info('Clearing solution data.')
for solution in self/'solutions':
solution.java.clearSolutionData()
log.info('Finished clearing solutions.')
log.info('Clearing mesh data.')
for mesh in self/'meshes':
mesh.java.clearMesh()
log.info('Finished clearing meshes.')
[docs]
def reset(self):
"""Resets the modeling history."""
log.info('Resetting modeling history.')
self.java.resetHist()
log.info('Finished resetting history.')
[docs]
def save(self, path: Path | str = None, format: str = None):
"""
Saves the model at the given file-system path.
If `path` is not given, the original file name is used, i.e. the one
from which the model was loaded to begin with. If the path contains no
folder information, the current folder (working directory) is used. If
the path points to a folder, the model name is used to name the file
inside that folder.
A `format` can be specified as either "Comsol", "Java", "Matlab", or
"VBA". If no format is given, it will be deduced from the file's
ending, being either `.mph`, `.java`, `.m`, or `.vba`, respectively.
No file ending implies "Comsol" format.
Imposes the correct file ending for the format. Overwrites existing
files.
"""
# Coerce paths given as string to Path objects.
if path:
path = Path(path)
# Possibly deduce format from file ending.
if format is None:
suffix = path.suffix if path else '.mph'
if suffix in ('.mph', ''):
format = 'Comsol'
elif suffix == '.java':
format = 'Java'
elif suffix == '.m':
format = 'Matlab'
elif suffix == '.vba':
format = 'VBA'
else:
error = f'Cannot deduce file format from ending "{suffix}".'
log.error(error)
raise ValueError(error)
# Allow synonyms for format and map to Comsol's file type.
if format in ('Comsol', 'mph', '.mph'):
(format, type) = ('Comsol', 'mph')
elif format in ('Java', 'java', '.java'):
(format, type) = ('Java', 'java')
elif format in ('Matlab', 'm', '.m'):
(format, type) = ('Matlab', 'm')
elif format in ('VBA', 'vba', '.vba'):
(format, type) = ('VBA', 'vba')
else:
error = f'Invalid file format "{format}".'
log.error(error)
raise ValueError(error)
# Use model name if no file name specified.
if path is None:
file = self.file()
if format == 'Comsol':
if file.is_file():
log.info(f'Saving model "{self}".')
self.java.save()
elif file.is_dir():
file = file/f'{self}.{type}'
log.info(f'Saving model as "{file.name}".')
self.java.save(str(file))
else:
if file.is_file():
file = file.with_suffix(f'.{type}')
elif file.is_dir():
file = file/f'{self}.{type}'
log.info(f'Saving model as "{file.name}".')
self.java.save(str(file), type)
# Otherwise save at given path.
else:
if path.is_dir():
file = (
path/self.name() # pyright: ignore[reportOperatorIssue]
).with_suffix(f'.{type}')
else:
file = path.with_suffix(f'.{type}')
log.info(f'Saving model as "{file.name}".')
if format == 'Comsol':
self.java.save(str(file))
else:
self.java.save(str(file), type)
log.info('Finished saving model.')