Node

class Node(model, path=None)[source]

Represents a model node.

This class makes it possible to navigate the model tree, inspect a node, namely its properties, and manipulate it, like toggling it on/off, creating child nodes, or “running” it.

Instances of this class reference a node in the model tree and work similarly to pathlib.Path objects from Python’s standard library. They support string concatenation to the right with the division operator in order to reference child nodes:

>>> node = model/'functions'
>>> node
Node('functions')
>>> node/'step'
Node('functions/step')

Note how the model object also supports the division operator in order to generate node references. As mere references, nodes must must not necessarily exist in the model tree:

>>> (node/'new function').exists()
False

In interactive sessions, the convenience function mph.tree() may prove useful to see the node’s branch in the model tree at a glance:

>>> mph.tree(model/'physics')
physics
├─ electrostatic
│  ├─ Laplace equation
│  ├─ zero charge
│  ├─ initial values
│  ├─ anode
│  └─ cathode
└─ electric currents
   ├─ current conservation
   ├─ insulation
   ├─ initial values
   ├─ anode
   └─ cathode

In rare cases, the node name itself might contain a forward slash, such as the dataset sweep/solution that happens to exist in the demo model from the Tutorial. These literal forward slashes can be escaped by doubling the character:

>>> node = model/'datasets/sweep//solution'
>>> node.name()
'sweep//solution'
>>> node.parent()
Node('datasets')

If the node refers to an existing model feature, then the instance wraps the corresponding Java object, which could belong to a variety of classes, but would necessarily implement the com.comsol.model.ModelEntity interface. That Java object can be accessed directly via the .java property. The full Comsol functionality is thus available if needed. The convenience function mph.inspect() is provided for introspection of the Java object in an interactive session.

model

Model object this node refers to.

groups

Mapping of the built-in groups to corresponding Java objects.

alias

Accepted aliases for the names of built-in groups.

path

Path of this node reference from the model’s root.

property java

Java object this node maps to, if any.

Note that this is a property, not an attribute. Internally, it is a function that performs a top-down search of the model tree in order to resolve the node reference. So it introduces a certain overhead every time it is accessed.

name()[source]

Returns the node’s name.

tag()[source]

Returns the node’s tag.

type()[source]

Returns the node’s feature type.

This a something like 'Block' for “a right-angled solid or surface block in 3D”. Refer to the Comsol documentation for details. Feature types are displayed in the Comsol GUI at the top of the Settings tab.

parent()[source]

Returns the parent node.

children()[source]

Returns all child nodes.

is_root()[source]

Checks if the node is the model’s root node.

is_group()[source]

Checks if the node refers to a built-in group.

exists()[source]

Checks if the node exists in the model tree.

comment(text=None)[source]

Returns or sets the comment attached to the node.

problems()[source]

Returns problems reported by the node and its descendants.

The problems are returned as a list of dictionaries, each with an entry for 'message' (the warning or error message), 'category' (either 'warning' or 'error'), 'node' (either this one or a node beneath it in the model tree), and 'selection' (an empty string if not applicable).

Calling this method on the root node returns all warnings and errors in geometry, mesh, and solver sequences.

rename(name)[source]

Renames the node.

retag(tag)[source]

Assigns a new tag to the node.

property(name, value=None)[source]

Returns or changes the value of the named property.

If no value is given, returns the value of property name. Otherwise sets the property to the given value.

properties()[source]

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

In the Comsol GUI, properties are displayed in the Settings tab of the model node.

select(entity)[source]

Assigns entity as the node’s selection.

entity can either be another node representing a selection feature, in which case a “named” selection is created. Or it can be a list/array of integers denoting domain, boundary, edge, or point numbers (depending on which of those the selection requires), producing a “manual” selection. It may also be 'all' to select everything or None to clear the selection.

Raises NotImplementedError if the node (that this method is called on) is a geometry node. These may be supported in a future release. Meanwhile, access their Java methods directly. Raises TypeError if the node does not have a selection and is not itself an “explicit” selection.

selection()[source]

Returns the entity or entities the node has selected.

If it is a “named” selection, the corresponding selection node is returned. If it is a “manual” selection, an array of domain, boundary, edge, or point numbers is returned (depending on which of those the selection holds). None is returned if nothing is selected.

Raises NotImplementedError if the node is a geometry node. These may be supported in a future release. Meanwhile, access their Java methods directly. Raises TypeError if the node does not have a selection and is not itself a selection.

toggle(action='flip')[source]

Enables or disables the node.

If action is 'flip' (the default), it enables the feature in the model tree if it is currently disabled or disables it if enabled. Pass 'enable' or 'on' to enable the feature regardless of its current state. Pass 'disable' or 'off' to disable it.

run()[source]

Performs the “run” action if the node implements it.

import_(file)[source]

Imports external data from the given file.

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.

create(*arguments, name=None)[source]

Creates a new child node and returns that node instance.

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.

If name is not given, a unique name/label will be assigned automatically.

remove()[source]

Removes the node from the model tree.