Skip to main content

mariepy

Electromagnetic simulation of MRI transmit coils and virtual observation points for SAR, ported from MARIE 3.0.

Tests codecov PyPI License: GPL v3+

Install

pip install mariepy

Usage

Build a coil and a body, and solve them together at the Larmor frequency of the field strength you name. Both are built in code here. A case laid out as MARIE lays it out — a simulation file in data/inputs/, its body in data/bodies/, its coil in data/coils/coil_files/ — is read whole:

from mariepy.inputs import read_case

case = read_case("data/inputs/my_case.json")
result = solve(
    case.body, case.coil, case.medium, linear=case.linear, shield=case.shield
)

VoxelBody.read_marie, SurfaceMesh.read_gmsh22 and read_lumped_elements read each file on its own.

from mariepy.body import VoxelBody
from mariepy.coil import Port, SurfaceCoil
from mariepy.constants import Medium
from mariepy.mesh import SurfaceMesh
from mariepy.solver import solve

medium = Medium(3.0)  # 1H at 3 T
body = VoxelBody.sphere(0.07, 0.005, 52.0, 0.55, padding=2)
coil = SurfaceCoil.build(
    SurfaceMesh.loop(radius=0.12, width=0.01, n_around=48, n_across=2),
    (Port(tag=1, kind="port", load="none", value=0.0, quality=1.0, voltage=1.0),),
)

result = solve(body, coil, medium)

result.impedance, result.admittance and result.scattering are the port matrices; result.fields.electric and result.fields.magnetic are each port's field over the body grid, shaped (n_ports, 3, n1, n2, n3). From there:

from mariepy.fields import absorbed_power, circular_components

watts = absorbed_power(result.operator, result.fields)
b1_plus, b1_minus = circular_components(result.operator, result.fields)

A wire coil, WireCoil.read_gmsh22 or WireCoil.loop, goes to solve in the same place, and so does a CombinedCoil of a wire coil and a surface coil; a simulation file naming a WireFile, with or without a CoilFile, reads into one of them.

linear=True gives the body the piecewise-linear basis, twelve unknowns per voxel, which carries the field's variation inside each voxel; the fields then come back as those coefficients, and fields.at_centres gives their values at the voxel centres.

The solve runs on either device: build the body and the coil with device="cuda" and everything downstream follows.

Tuning, matching and calibration

A coil's lumped elements are closed by co-simulation, as MARIE does it. Solve the coil with its tunable elements opened into ports ("TMD": 1 in the simulation file), then search their values, the matching networks' and the decoupling, and calibrate the fields to the wave driving each matched port:

from mariepy.cosim import calibrate, co_simulate

closed = co_simulate(case.network, result.admittance, case.medium.angular_frequency)
electric = calibrate(result.fields.electric, closed.transmit)

With "TMD": 0 the file's values are placed as they are. closed.transmit has a column per transmitting port and closed.receive one per receiving port, as the element file assigns Tx, Rx and TxRx; closed.scattering is the transmitting ports' reflection and coupling; cosim.sweep gives the matched ports across a band.

Field bases, SNR and figures

A body's field basis is built once from a support surface around it (basis.surface_basis) or from a shell of currents around it (basis.dipole_basis), and any coil near that support is then solved through it:

from mariepy import basis, metrics, plot
from mariepy.solver import assemble_coil

incident = basis.surface_basis(case.body, case.basis_support, case.medium)
solved = basis.solve(incident, case.body, case.medium)
system = assemble_coil(case.coil, case.medium)
reduced = basis.solve_coil(case.coil, system, solved, case.body, case.medium)
ultimate_snr, ultimate_efficiency = basis.ultimate_maps(solved, case.body, case.medium)

metrics.noise_covariance, metrics.snr, metrics.transmit_efficiency and metrics.g_factor map a coil's performance from its fields; plot.geometry, plot.coil_currents, plot.scattering, plot.sweep and plot.slices draw the model and the maps.

Head models, body coils, arrays and field maps

A segmentation that gives each voxel the fraction every tissue fills is averaged onto the solver's grid and mixed into a body; a body coil enters as the modes of an infinitely long birdcage; an array is a set of loops, one port each; and each coil's circular field components are written for a simulator:

import math
from mariepy import fields, incident, maps, tissue
from mariepy.solver import solve, solve_incident
from mariepy.wire import WireCoil

head = tissue.mix(tissue.coarsen(fractions, 5), table, medium, 5e-3)
modes = [incident.birdcage(head.body, medium, angle=a) for a in (0.0, math.pi / 2)]
body_coil = solve_incident(
    head.body,
    medium,
    torch.stack([e for e, _ in modes]),
    torch.stack([h for _, h in modes]),
)
array = solve(head.body, WireCoil.loops(centres, normals, 0.04, 36), medium)
open_ports = fields.combine(array.fields, array.impedance)  # 1 A each, the rest open
plus, minus = fields.circular_components(medium, open_ports)

examples/brainweb.py does this for BrainWeb's normal brain in a body coil and three head arrays, and writes each coil's maps with maps.write and the transmit coils' VOPs with vop.write.

Command line

mariepy solve my_case.json --data marie-tools/data --out ports.npz
mariepy vops my_case.json --data marie-tools/data --labels labels.npy \
    --table tissue.csv --out vops.npz --safety-factor 1.5 --safety-basis "..."
mariepy vops --sphere --out vops.npz --safety-factor 1 --safety-basis "demo"

solve prints the port solve, reciprocity, power balance, co-simulation and B1+ and SNR summaries, and --out keeps the admittance and scattering matrices. vops writes the file vop.read reads; without --labels and --table the case's own tissue properties are used with --density. The file carries --safety-factor, which every local SAR read from it is multiplied by, with --safety-basis stating what it covers, and optionally --transmit, the transmit configuration it is valid for. examples/tissue_gabriel.csv shows the table's columns.

Development

See CONTRIBUTING.md.

Licence

Copyright (C) 2026 Matteo Cencini. mariepy is free software under the GNU General Public License, version 3 or any later version; see LICENSE. Code it carries from other projects, and their notices, are listed in THIRD_PARTY.md.

The licence covers the program. The files it writes, such as VOP files and field maps, are the user's and carry whatever terms their body models impose (see PLAN.md), so projects under any licence can read them.

Metadata

Release files for mariepy 0.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mariepy 0.0.2
File Size Uploaded Provenance Actions
mariepy-0.0.2.tar.gz 439.5 kB With provenance Details for mariepy-0.0.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for mariepy 0.0.2
File Actions
mariepy-0.0.2-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.24+ x86-64, Linux glibc 2.28+ x86-64 Details for mariepy-0.0.2-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
mariepy-0.0.2-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for mariepy-0.0.2-cp314-cp314-macosx_11_0_arm64.whl
mariepy-0.0.2-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.24+ x86-64, Linux glibc 2.28+ x86-64 Details for mariepy-0.0.2-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
mariepy-0.0.2-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details for mariepy-0.0.2-cp313-cp313-macosx_11_0_arm64.whl
mariepy-0.0.2-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64, Linux glibc 2.24+ x86-64 Details for mariepy-0.0.2-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
mariepy-0.0.2-cp312-cp312-macosx_11_0_arm64.whl CPython 3.12 CPython 3.12 macOS 11.0+ ARM64 Details for mariepy-0.0.2-cp312-cp312-macosx_11_0_arm64.whl
mariepy-0.0.2-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.24+ x86-64, Linux glibc 2.28+ x86-64 Details for mariepy-0.0.2-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
mariepy-0.0.2-cp311-cp311-macosx_11_0_arm64.whl CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details for mariepy-0.0.2-cp311-cp311-macosx_11_0_arm64.whl
mariepy-0.0.2-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64, Linux glibc 2.24+ x86-64 Details for mariepy-0.0.2-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
mariepy-0.0.2-cp310-cp310-macosx_11_0_arm64.whl CPython 3.10 CPython 3.10 macOS 11.0+ ARM64 Details for mariepy-0.0.2-cp310-cp310-macosx_11_0_arm64.whl

Total release size: 6.0 MB

Release files / mariepy-0.0.2.tar.gz

Download URL mariepy-0.0.2.tar.gz
Size 439.5 kB
Tags Source
SHA-256 checksum
How to use checksums
c415c07247f02e5322edd16725bc27a6bd80c1c7135a74b9a48ab91e9f07f306
BLAKE2b-256 checksum
How to use checksums
856918b8732b505681a38039431f012ceb545c5c4d719e85fbe0a31025320d1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL mariepy-0.0.2-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 636.1 kB
Tags CPython 3.14 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
b5c884c92222f7cf3530693cfa3fd5453db928f5991cc1d562e214d52ba9ead1
BLAKE2b-256 checksum
How to use checksums
a99be4c85d9695c254240bdc7b2b14dac12929cee6c59ab1758833afbbe85652
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp314-cp314-macosx_11_0_arm64.whl

Download URL mariepy-0.0.2-cp314-cp314-macosx_11_0_arm64.whl
Size 470.7 kB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
e3b49f5f627bff4b591c7cf47e5d5a70e1d009ece6ad3a33f92666778c7be686
BLAKE2b-256 checksum
How to use checksums
dade8709d47934cf805f1f6593c43063c6cc836b8402184adc09a774cd4cd7bc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL mariepy-0.0.2-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 635.8 kB
Tags CPython 3.13 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
79e0c1b9b8f8a067b86be17519f8bca60f9e4c302171c44c77dda7fc2f935b46
BLAKE2b-256 checksum
How to use checksums
552d7b4858b46ea372a0f3458fd9b9940907c28327f1240eb8142450eec771cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp313-cp313-macosx_11_0_arm64.whl

Download URL mariepy-0.0.2-cp313-cp313-macosx_11_0_arm64.whl
Size 470.4 kB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
4b1966314fb9365e649aaeacf57e9a7579c52df232425ba5cfe35058b3324d48
BLAKE2b-256 checksum
How to use checksums
0d10b7dbb23ea7b7c312140ec230e22b51e1b01661b833a80feb0ed32758908b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL mariepy-0.0.2-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 635.8 kB
Tags CPython 3.12 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
cb95ff0ec2a20372de4d406930d4dd9937e5622136719cd1274e20abc6b9a6d8
BLAKE2b-256 checksum
How to use checksums
c4b57a0ae1c8748b5659c1967de348a13103120175dbc6f3374d96a8435ffa1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp312-cp312-macosx_11_0_arm64.whl

Download URL mariepy-0.0.2-cp312-cp312-macosx_11_0_arm64.whl
Size 470.3 kB
Tags CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
667a50c4faffecf64a65d3650cca6e41e365b3c9e676d0f481d9f332b58a710f
BLAKE2b-256 checksum
How to use checksums
5cdf58a4bed3cfc5721e0adb416273cebe02b3bfb6e704f8015dea682f8f8d94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL mariepy-0.0.2-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 637.3 kB
Tags CPython 3.11 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
11a467b8d2cf0bab41efccd3523aa627702e9254b4ee3c0e1838b57f3deed886
BLAKE2b-256 checksum
How to use checksums
d07d92a63ee2d685b91acd76b9f77f36ab34124be6e2033729505ea7e2c8b2b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp311-cp311-macosx_11_0_arm64.whl

Download URL mariepy-0.0.2-cp311-cp311-macosx_11_0_arm64.whl
Size 466.4 kB
Tags CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
9f2518c2512fe430e6bf726d97ebbd328d8a6b867a68cf6605ad8b3a91baefb8
BLAKE2b-256 checksum
How to use checksums
65559b0b8cadfef443af9c7b8dfed497d7bccf9f076c1f130294d5c9ca578d39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

Download URL mariepy-0.0.2-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Size 632.7 kB
Tags CPython 3.10 Linux glibc 2.24+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
ee55df6e0adacaaa947bf62a7823fedc734fc18368623da832e23765240c2d21
BLAKE2b-256 checksum
How to use checksums
9c30eecdde3bb55909c3f92f6b4a08ac2ed9fde151a5ff376b9eca33c93cdc74
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / mariepy-0.0.2-cp310-cp310-macosx_11_0_arm64.whl

Download URL mariepy-0.0.2-cp310-cp310-macosx_11_0_arm64.whl
Size 464.1 kB
Tags CPython 3.10 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
0193a664f712644329b2e04eadb85a662568596e7ca487b418f1a521e19713ff
BLAKE2b-256 checksum
How to use checksums
6a3a70de38864c0debe80dbe188abceb7aa710206805c845a8f6d0357c05b86b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for mariepy 0.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 11 files in this release have been uploaded with provenance metadata.

Select from 11 files

Attestation for mariepy-0.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.2 This release

11 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page