All about constraint files

This page explains how Shimming Toolbox uses constraint files to respect the limits of your shim coil when optimizing the shim coefficients. Both scanner coil and custom coil constraint files are discussed.

What are constraint files?

A constraint file is a JSON file that lists the different parameters used by Shimming Toolbox to generate a shim solution that respects the constraints of your shim coil.

Do I need to use a constraint file?

Some shim algorithms do not support constraints, see Which shim algorithms support constraints? for more information. If the algorithm you wish to use does not support constraints, then even if you supply a constraint file, the shim solution won't respect them. A warning should inform you that the constraints are not being respected. Custom coils require constraint files to be used while scanner coils are optional using the --scanner-coil-constraints argument. See Do I need to use a scanner constraint file? for more information.

Scanner constraint files

What is in the scanner constraint file?

The scanner constraint file lists the different hardware limits to respect when optimizing.

The file contains the following fields:

name: The name of the scanner. This will be used when creating the name of the output shim file.
coef_channel_minmax: A dictionary that lists the minimum and maximum values for each shim channel. The keys of the dictionary are the order of the shim coefficients (0 for spherical harmonic order 0 (frequency), 1 for order 1 (X, Y, Z), 2 for order 2 (Z2, ZX, ZY, X2 - Y2, XY) and 3 for order 3 (Z3, Z2X, Z2Y, Z(X2 - Y2), XYZ, X(X2 - Y2), Y(X2 - Y2)). When using Siemens 3rd order shim (which only have 4 channels), use a list of 4 channels in the order described above.
coef_sum_max: Number specifying the maximum allowed sum of the absolute values of the shim coefficients. Scanner's typically do not have a limit for this, you can write null to disregard the constraint. This option is usually useful for custom constraint files, not scanner constraint files.
coefs_used: A dictionary to specify the shim value used when acquiring the B0 map. These values are specified in the same order as coef_channel_minmax. Use null instead of a list of values to let Shimming Toolbox read the metadata of the B0 map to figure out these values. See Option 1: How can Shimming Toolbox know the current shim values and scanners constraints automatically (recommended) for more information.

Here is an example of a scanner constraint file for a Siemens MAGNETOM Prisma Fit.:

{
    "name": "MAGNETOM Prisma Fit",
    "coef_channel_minmax":
    {
        "0": [[123100100, 123265000]],
        "1": [[-2300, 2300],
              [-2300, 2300],
              [-2300, 2300]],
        "2": [[-4959.01, 4959.01],
              [-3551.29, 3551.29],
              [-3503.299, 3503.299],
              [-3551.29, 3551.29],
              [-3487.302, 3487.302]]
    },
    "coef_sum_max": null,
    "coefs_used":
    {
        "0": [0],
        "1": [0, 0, 0],
        "2": [0, 0, 0, 0, 0]
    }
}

Do I need to use a scanner constraint file?

When using an algorithm that supports constraints (see Which shim algorithms support constraints?), Shimming Toolbox needs to know different scanner parameters to respect the scanner's limits (i.e.: the minimum and maximum shim coefficient for each channel, the current shim coefficients). There are 2 ways for Shimming Toolbox to know the scanner constraints:

We store the shim constraints of specific scanners internally (no need for a scanner constraint file).
Provide these parameters in a file using the --scanner-coil-constraints argument when running st_b0shim dynamic or st_b0shim realtime. This file will overwrite the internal scanner constraints if provided.

Option 1: How can Shimming Toolbox know the current shim values and scanners constraints automatically (recommended)

The benefit of this option is that you don't need to fill the current shim coefficients (coefs_used) yourself everytime you shim. You also don't need to add the --scanner-coil-constraints option to the command. This reduces the risk of human error and saves you time at the scanner.

You can inspect the list of currently implemented scanners in "shimming-toolbox/shimmin-toolbox/shimmingtoolbox/coils/coil.py".

Siemens

Since Siemens writes the shim coefficient of orders 0, 1 and 2 in the DICOM metadata, they are also available in the BIDS sidecar which Shimming Toolbox can access. The values of orders 1 and 2 are stored using DAC units instead of uT/m and uT/m^2 which needs scanner specific conversion factors. These conversion factors can be calculated from running both of these commands in the terminal on the scanner:

AdjValidate -shim -info -mp
AdjValidate -shim -info

The order 0 minimum and maximum value can be found in the manual frequency adjustment tab when a protocol is loaded on the scanner.

To add your scanner to the internal list of supported scanners, you can send us, by opening an issue, the output of both AdjValidate commands, the order 0 (frequency) minimum and maximum values, and a BIDS JSON sidecar of an acquisition on your scanner (to identify your scanner's name and unique number).

For order 3, Siemens does not include the current shim values in the DICOM metadata, you therefore need to fill the current values of order 3 in the scanner constraint file yourself. See Option 2: How do I find the values to fill in the scanner constraint file? for more information.

Philips

Philips does not store the shim coefficients (orders 1, 2 and 3) in the DICOM metadata, it is therefore not possible to automatically read the current shim values automatically from a DICOM to NIfTI conversion. We have developped a patch to improve Shimming Toolbox's compatibility with Philips scanners. The patch automatically generates a constraint file for each acquisition. You can contact us to get this patch and instructions on how to use it.

GE

GE only stores the orders 0 and 1 shim coefficients in the DICOM metadata. Contact us by opening an issue if you want to use Shimming Toolbox with a GE scanner so we can figure out the best way to read the current shim values and store the scanner's constraints.

Other manufacturers

For other manufacturers, please reach out to us so we can find how to read the current shim values and store the scanner's constraints.

Option 2: How do I find the values to fill in the scanner constraint file?

Siemens

The order 0 (frequency) minimum and maximum values can be found in the manual frequency adjustment tab when a protocol is loaded on the scanner.

Orders 1 and 2 can be found by using the following command in the terminal on the scanner:

AdjValidate -shim -info -mp

The output will be in the same order as coef_channel_minmax.

The current frequency (order 0) will automatically be read from the B0 map metadata, coef_channel_minmax[0] should therefore be null.

Orders 1, 2 and 3 can be found in two different way. Either in the manual shim adjustment tab or with the following command:

AdjValidate -shim -get -mp

The coefficent values to fill in are in the same units as that tab (uT/m, uT/m^2, uT/m^3).

Philips

We recommend contacting us when using Shimming Toolbox with Philips scanners as we have made a patch to improve Shimming Toolbox's compatibility with Philips scanners. The patch automatically generates a constraint file for each acquisition.

Other manufacturers

For other scanners, please reach out to us so we can help figure out the correct values to fill in.

Custom coil constraint files

What are custom coil constraint files

The coil constraint file is a JSON file that lists the different parameters used by Shimming Toolbox to respect the custom coils contraints.

Here are the different fields in the coil constraint file:

name: The name of the coil. This will be used when creating the name of the output shim file.
coef_channel_minmax: A dictionary that lists the minimum and maximum values for each shim channel. We don't enforce units but your coil profiles need to be consistent (if your coil profiles are in Hz/A, then these values are in A, if your coil profiles are in Hz/mA, then these values should be in mA). Use null to set the limit to infinity.
coef_sum_max: Number specifying the maximum allowed sum of the absolute values of the shim coefficients. Use null to set the limit to infinity.
coefs_used: A dictionary to specify the shim value used when acquiring the B0 map. These values are specified in the same order as coef_channel_minmax. These will typically be 0.
Units: Used for display purposes only and does not affect any shim current output.

{
    "name": "custom",
    "coef_channel_minmax":
    {
        "coil": [[-2.5, 2.5],
                 [-2.5, 2.5],
                 [-2.5, 2.5],
                 [-2.5, 2.5],
                 [-2.5, 2.5],
                 [-2.5, 2.5],
                 [-2.5, 2.5],
                 [-2.5, 2.5],
                 [-2.5, 2.5]]
    },
    "coef_sum_max": 20,
    "coefs_used":
    {
        "coil": [0, 0, 0, 0, 0, 0, 0, 0, 0]
    },
    "Units": "A"
}

This file gets populated with the correct values when running st_create_coil_profiles. For more information, see the Create B0 Coil Profiles tutorial.

Which shim algorithms support constraints?

The following algorithms support scanner constraints (--optimizer-method):

least_squares: Minimum and maximum bounds (coef_channel_minmax), and maximum sum of absolute values (coef_sum_max)
quad_prog: Minimum and maximum bounds (coef_channel_minmax), and maximum sum of absolute values (coef_sum_max)
bfgs: Minimum and maximum bounds (coef_channel_minmax)

The following algorithms do not support scanner constraints:

pseudo_inverse