JCMsuite Python Interface (jcmsuite)

Python interface for JCMsuite solver workflows. Run projects, manage local and daemon execution, and inspect or export result data from Python.

Features

• Project execution: Generate meshes and run JCMsuite projects from Python.
• Parameterized projects: Supply project keys to templates, including nested values and numeric arrays, to vary geometry, materials, and sources.
• Parameter scans: Run ordered batches with isolated working directories.
• Parallel execution: Schedule solves on local or remote workstations and configured cluster queues through the JCMsuite daemon.
• Structured results: Inspect costs, eigenvalues, postprocesses, and exported fields. Supported result types export to dictionaries, pandas, and xarray.
• Persistent results: Store and reuse matching solves with Resultbag.

Requirements

• Python 3.13 or later.
• A separate JCMsuite installation for solver operations.

Installing this Python package does not install the JCMsuite solver. Test licenses are available to try JCMsuite; you do not need an existing commercial license to get started. See the JCMsuite documentation for installation instructions and license information.

Installation

python -m pip install jcmsuite

The installation includes NumPy, pandas, SciPy, xarray, and the jcmsuite-data-tree support package. Optional features are available as extras:

python -m pip install "jcmsuite[progress]"  # tqdm progress bars
python -m pip install "jcmsuite[torch]"     # PyTorch integration
python -m pip install "jcmsuite[all]"       # both optional features

Getting Started

Locate JCMsuite

Set the JCMROOT environment variable to your JCMsuite installation directory before starting Python. Then inspect the installation:

import jcmsuite

jcmsuite.info()

Alternatively, select an installation explicitly with a context. Replace the example path with your installation directory:

from jcmsuite.context import create_context

context = create_context(jcm_root="/path/to/JCMsuite")
with context:
    jcmsuite.info()

The context is active only inside the with block. The examples below use the default context configured through JCMROOT.

Run A Project And Inspect Results

Pass the path of an existing JCMsuite project to solve:

result = jcmsuite.solve("project.jcmp")

project.jcmp represents a project that you supply; it is not included in this package. By default, solve waits for completion and returns a SolveResult. The available data depends on the project and its declared postprocesses. For a project with at least one postprocess, inspect its first record:

postprocess = result.postprocesses[0]
print(postprocess.to_dict())

Field exports also support operations such as selecting a field and calculating its intensity. Use jcmsuite.view(result.file) to open an available solution fieldbag in JCMview. JCMview requires a graphical environment.

Pass Project Keys And Run A Scan

For a project whose templates already accept a radius key, pass its value through keys:

result = jcmsuite.solve("project.jcmp", keys={"radius": 0.3})

For a scan, pass a list of project-key dictionaries instead:

keys = [{"radius": radius} for radius in (0.3, 0.4, 0.5)]
results = jcmsuite.solve("project.jcmp", keys=keys, temporary=True, quiet=True)

The returned BatchSolveResult preserves input order. temporary=True gives each solve an isolated working directory so that scan entries do not overwrite each other's files. quiet=True suppresses local solver output. For compatible postprocess data, combine the scan results with results.postprocesses[0].to_xarray().

Run Solves In Parallel Or Reuse Results

To run the same scan through a local daemon, declare a resource and activate the handler around the solve:

handler = jcmsuite.daemon.handler()
handler.resources.add(
    jcmsuite.daemon.Workstation(hostname="localhost", multiplicity=2, n_threads=1)
)
with handler:
    results = jcmsuite.solve("project.jcmp", keys=keys, temporary=True, quiet=True)

This configuration allows two concurrent solves with one solver thread each. Choose values supported by your computer and available JCMsuite licenses. The handler disconnects and stops the daemon when the block ends.

For repeated scans, pass a Resultbag with resultbag= to store results and reuse entries that match the project, project keys, suffix pattern, and source-file state. Open Resultbag files only from trusted sources: loading them uses Python pickle and can execute code.

Documentation and Support

See the JCMsuite documentation for manuals, tutorials, and installation instructions. For product and support information, visit JCMwave.

The related jcmsuite-data-tree and jcmsuite-notebooks packages provide low-level tree helpers and notebook/Matlab conversion tools. They do not replace the main jcmsuite solver interface.

License

This Python package is licensed under the MIT License. JCMsuite solver licensing is separate.