Metadata-Version: 2.4
Name: jcmsuite
Version: 7.4.2
Summary: The JCMwave Python interface provides access to the JCMsuite software.
License-Expression: MIT
Author: Matthias Plock
Author-email: matthias.plock@jcmwave.com
Requires-Python: >=3.13
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: all
Provides-Extra: progress
Provides-Extra: torch
Requires-Dist: jcmsuite-data-tree (>=7.4.2,<7.5.0)
Requires-Dist: numpy (>=2.1.0,<3.0)
Requires-Dist: pandas (>=2.2.3,<4.0)
Requires-Dist: scipy (>=1.14.1,<2.0)
Requires-Dist: torch (>=2.6,<3.0) ; extra == "all"
Requires-Dist: torch (>=2.6,<3.0) ; extra == "torch"
Requires-Dist: tqdm (>=4.50,<5.0) ; extra == "all"
Requires-Dist: tqdm (>=4.50,<5.0) ; extra == "progress"
Requires-Dist: xarray (>=2024.10.0,<2027.0)
Project-URL: Documentation, https://docs.jcmwave.com/JCMsuite/html/
Project-URL: Homepage, https://www.jcmwave.com
Description-Content-Type: text/markdown

# 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](https://docs.jcmwave.com/JCMsuite/html/) for installation
instructions and license information.

## Installation

```bash
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:

```bash
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:

```python
import jcmsuite

jcmsuite.info()
```

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

```python
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`:

```python
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:

```python
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`:

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

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

```python
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:

```python
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](https://docs.jcmwave.com/JCMsuite/html/) for
manuals, tutorials, and installation instructions. For product and support
information, visit [JCMwave](https://www.jcmwave.com).

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.

