Model

class Model(parent)

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.

Example usage:

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 class.

This class is a wrapper around the com.comsol.model.Model 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.

java

Java object that this instance is wrapped around.

name()

Returns the model’s name.

file()

Returns the absolute path to the file the model was loaded from.

version()

Returns the Comsol version the model was last saved with.

functions()

Returns the names of all globally defined functions.

components()

Returns the names of all model components.

geometries()

Returns the names of all geometry sequences.

selections()

Returns the names of all selections.

physics()

Returns the names of all physics interfaces.

multiphysics()

Returns the names of all multiphysics interfaces.

materials()

Returns the names of all materials.

meshes()

Returns the names of all mesh sequences.

studies()

Returns the names of all studies.

solutions()

Returns the names of all solutions.

datasets()

Returns the names of all datasets.

plots()

Returns the names of all plots.

exports()

Returns the names of all exports.

modules()

Returns the names of modules/products required to be licensed.

problems()

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() on how problems (error/warning messages and their origin) are returned.

build(geometry=None)

Builds the named geometry, or all of them if none given.

mesh(mesh=None)

Runs the named mesh sequence, or all of them if none given.

solve(study=None)

Solves the named study, or all of them if none given.

inner(dataset=None)

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.

outer(dataset=None)

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.

evaluate(expression, unit=None, dataset=None, inner=None, outer=None)

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, of whichever dimensionality they may then have.

A dataset may be specified. Otherwise 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.

Please note that this method, while broad in its intended scope, covers common use cases, but not all of them. In case it fails to return the expected results, consider using the Comsol API features directly via the .java attribute of this class, and refer to the “Results” chapter in the Comsol Programming Manual for guidance. A known limitation is the evaluation of field variables in time-dependent parameter sweeps, where not all time steps are returned: see issues #120 and #119.

rename(name)

Assigns a new name to the model.

parameter(name, value=None, unit=None, description=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.

Warning: The optional arguments unit and description are deprecated and will be removed in a future release. Include the unit in the value expression and call the description() method to change a parameter description.

parameters(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.

Warning: Prior to version 1.0, this method would return a list of named tuples holding name, value, and description. It now returns a dictionary, which is a breaking change that may require application code to be adapted. The descriptions can be retrieved by additionally calling .description() or .descriptions().

description(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.

descriptions()

Returns all parameter descriptions as a dictionary.

property(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.

properties(node)

Returns names and values of all node properties as a dictionary.

create(node, *arguments)

Creates a new child node.

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 the values of 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.

remove(node)

Removes the node from the model tree.

import_(node, file)

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.

export(node=None, file=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.

clear()

Clears stored solution, mesh, and plot data.

reset()

Resets the modeling history.

save(path=None, format=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.