MPh Documentation

While MPh provides an idiomatic Python API for common tasks, you can access the complete Comsol API using the .java attribute on Client or Model instances. This attribute exposes the underlying Java layer via JPype, mapping to Comsol's ModelUtil and model objects respectively. This allows you to translate existing Java or Matlab code from Comsol documentation directly into Python with minimal changes (e.g., replacing Java array syntax like new String[]{...} with Python lists [...]).

import mph

client = mph.start()
pmymodel = client.create('Model')
model = pymodel.java

# Now 'model' is a Java object allowing direct Comsol API calls
model.modelNode().create("comp1")
model.geom().create("geom1", 3)
model.geom("geom1").feature().create("blk1", "Block")
model.geom("geom1").feature("blk1").set("size", ["0.1", "0.2", "0.5"])
model.geom("geom1").run("fin")

# To save the model using the Python wrapper
pmymodel.save('model')

For more flexible model navigation, use the Node class. model.create() returns Node instances, which support the division operator (/) for path traversal, similar to pathlib.Path. This allows you to build hierarchical references cleanly.

Path Syntax Rules:

• Division Operator: model/'geometries'/'geometry'/'ice block' refers to a specific node.
• String Paths: model/'geometries/geometry/ice block' is also valid.
• Root Reference: Use model/'' or model/None to refer to the root.
• Escaping Slashes: If a node name contains a literal forward slash (e.g., ice/frozen water), escape it by doubling the slash: geometry/'ice//frozen water'.

import mph
client = mph.start()
model = client.create('block of ice')

# Using the division operator for navigation
geometries = model/'geometries'
geometry = geometries.create(3, name='geometry')
block = geometry.create('Block', name='ice block')
block.property('size', ('0.1', '0.2', '0.5'))

model.build(geometry)

MPh supports two modes of operation via the Client class or the mph.option() configuration:

1. Stand-alone mode: The client runs inside the same process as Python. It is more lightweight and faster for frequent API calls (like navigating the model tree with mph.tree()), but it is harder to set up on Unix-like systems.
2. Client-server mode: A 'thin' client connects to a separate Comsol server via a network socket. This is the default mode because it works out of the box on all platforms, but it has higher overhead for frequent API interactions.

Configuration Options

• Via Client class: If you provide a network port value, it runs in client-server mode. If you do not provide a port, it attempts stand-alone mode.
• Via mph.option(): You can set the 'session' option to:
  • 'client-server' (Default)
  • 'stand-alone'
  • 'platform-dependent' (Uses stand-alone on Windows, client-server on Linux/macOS)

Because a single Python process cannot run more than one Comsol session, you must use the multiprocessing module to achieve parallel execution. This allows you to run multiple Python processes, each managing its own mph.start() session, to perform tasks like parameter sweeps across multiple CPU cores.

Implementation Pattern

1. Define a Worker Function: The function should call mph.start(cores=1) inside the process to initialize a local Comsol session. It should pull tasks from a multiprocessing.Queue (jobs), perform the simulation, and push results to another multiprocessing.Queue (results).
2. Initialize Queues: Create a multiprocessing.Queue() for jobs and an empty one for results.
3. Spawn Processes: Use multiprocessing.Process to start multiple workers. It is recommended to keep references to these process objects in a list to prevent garbage collection from terminating them prematurely.
4. Collect Results: In the main process, iterate through the results queue to retrieve the completed data. Note that because processes run asynchronously, results may not be returned in the same order they were submitted.

This approach provides more programmatic control than Comsol's internal 'parametric sweep', making it suitable for iterative optimization algorithms like genetic algorithms.

import mph
import multiprocessing
import queue

# 1. Define the worker
def worker(jobs, results):
    client = mph.start(cores=1)
    model = client.load('capacitor.mph')
    while True:
        try:
            d = jobs.get(block=False)
        except queue.Empty:
            break
        model.parameter('d', f'{d} [mm]')
        model.solve('static')
        C = model.evaluate('2*es.intWe/U^2', 'pF')
        results.put((d, C))

# 2. Setup data and queues
values = [0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0]
jobs = multiprocessing.Queue()
for d in values:
    jobs.put(d)
results = multiprocessing.Queue()

# 3. Start workers
processes = []
for _ in range(4):
    process = multiprocessing.Process(target=worker, args=(jobs, results))
    process.start()
    processes.append(process)

# 4. Collect results
for _ in values:
    (d, C) = results.get()
    print(f"Distance: {d}, Capacitance: {C}")