Constraints

Gradient Amplitude

Problem definition for GrOpt gradient optimization.

This class holds the waveform dimensions, constraints, and objectives that define a gradient optimization problem.

add_gmax

add_gmax(gmax: float = 0.03, rot_variant: bool = True, weight_mod: float = 1.0) -> None

Add a maximum gradient amplitude constraint.

Parameters:

Name	Type	Description	Default
gmax	float	Maximum allowed gradient magnitude [T/m].	0.03
rot_variant	bool	If True, use rotationally invariant formulation.	True
weight_mod	float	Weighting factor for this constraint.	1.0

Slew Rate

Problem definition for GrOpt gradient optimization.

This class holds the waveform dimensions, constraints, and objectives that define a gradient optimization problem.

add_smax

add_smax(smax: float = 80.0, rot_variant: bool = True, weight_mod: float = 1.0) -> None

Add a maximum gradient slew rate constraint.

Parameters:

Name	Type	Description	Default
smax	float	Maximum allowed gradient slew rate [T/m/s].	80.0
rot_variant	bool	If True, use rotationally invariant formulation.	True
weight_mod	float	Weighting factor for this constraint.	1.0

Moments

Problem definition for GrOpt gradient optimization.

This class holds the waveform dimensions, constraints, and objectives that define a gradient optimization problem.

add_moment

add_moment(order: float = 0, target: float = 0.0, tol: float = 1e-06, units: str = 'mT*ms/m', axis: int = 0, start_idx: int = -1, stop_idx: int = -1, ref_idx: int = 0, weight_mod: float = 1.0) -> None

Add a moment constraint.

Parameters:

Name	Type	Description	Default
order	int	Moment order.	0
target	float	Target moment value.	0.0
tol	float	Tolerance for satisfying the constraint.	1e-06
units	str	Units: 'mTms/m', 'Ts/m', 'rad*s/m', or 's/m'.	'mT*ms/m'
axis	int	Axis for moment calculation.	0
start_idx	int	Starting index (-1 = beginning).	-1
stop_idx	int	Stopping index (-1 = end).	-1
ref_idx	int	Reference index (t=0 for moment calculations).	0
weight_mod	float	Weighting factor for this constraint.	1.0

b-value

Problem definition for GrOpt gradient optimization.

This class holds the waveform dimensions, constraints, and objectives that define a gradient optimization problem.

add_bvalue

add_bvalue(target: float = 100.0, tol: float = 1.0, start_idx0: int = -1, stop_idx0: int = -1, weight_mod: float = 1.0, mode: object = 2, max_scale: float = 1.01) -> None

Add a b-value constraint.

Parameters:

Name	Type	Description	Default
target	float	Target b-value.	100.0
tol	float	Tolerance for the b-value constraint.	1.0
start_idx0	int	Starting index (-1 = full waveform).	-1
stop_idx0	int	Stopping index (-1 = full waveform).	-1
weight_mod	float	Weighting factor.	1.0
mode	int or str	'setval'/1 = set b-value, 'minval'/2 = minimum b-value (default), 'minval_max'/3 = minimum b-value with scaling.	2
max_scale	float	Scale factor when mode=3.	1.01

PNS (SAFE-model)

PNS parameters can be loaded from an .asc file using the gropt.readasc.asc_to_safe function, which will create a python dictionary that can be used as input to the SAFE constraints. Alternatively, no parameters can be entered to use some default demonstration values. Finally, to get a SAFE prediction, the gropt.get_SAFE function can be used.

gropt.readasc.asc_to_safe

asc_to_safe(asc_file: str) -> tuple[dict, dict]

Convert an ASC file to SAFE format.

Parameters:

Name	Type	Description	Default
asc_file	str	Path to the ASC file.	required

Returns:

Type	Description
tuple[dict, dict]	SAFE hardware parameters. The first dictionary contains the parameters for the PNS model, and the second dictionary contains the parameters for the cardiac model. If the cardiac model is not available, the second dictionary will be None.

Problem definition for GrOpt gradient optimization.

This class holds the waveform dimensions, constraints, and objectives that define a gradient optimization problem.

add_SAFE

add_SAFE(stim_thresh: float = 1.0, new_first_axis: int = 0, demo_params: bool = True, safe_params: object | None = None, weight_mod: float = 1.0) -> None

Add a SAFE (PNS) constraint.

Parameters:

Name	Type	Description	Default
stim_thresh	float	Stimulus threshold for the SAFE constraint.	1.0
new_first_axis	int	Swap the first axis of the SAFE parameters.	0
demo_params	bool	Whether to use demo parameters. Ignored if safe_params is provided.	True
safe_params	dict	Dictionary of SAFE parameters (see gropt.readasc).	None
weight_mod	float	Weighting factor for this constraint.	1.0

add_SAFE_vec

add_SAFE_vec(stim_thresh_vec: Annotated[NDArray[float64], dict(shape=(None,), order=C)], new_first_axis: int = 0, demo_params: bool = True, safe_params: object | None = None, weight_mod: float = 1.0) -> None

Add a SAFE constraint with a vector stimulation limit.

Parameters:

Name	Type	Description	Default
stim_thresh_vec	ndarray	Vector of stimulus thresholds.	required
new_first_axis	int	Swap the first axis of the SAFE parameters.	0
demo_params	bool	Whether to use demo parameters.	True
safe_params	dict	Dictionary of SAFE parameters (see gropt.readasc).	None
weight_mod	float	Weighting factor for this constraint.	1.0

gropt.get_SAFE

get_SAFE(G: Annotated[NDArray[float64], dict(shape=(None,), order=C)], dt: float, true_safe: bool = True, new_first_axis: int = 0, demo_params: bool = True, safe_params: object | None = None) -> Annotated[NDArray[numpy.float64], dict(shape=(None,), order=C)]

Compute the SAFE (PNS) response for a gradient waveform.

Parameters:

Name	Type	Description	Default
G	ndarray	Gradient waveform.	required
dt	float	Raster time in seconds.	required
true_safe	bool	Use true SAFE model.	True
new_first_axis	int	Swap the first axis of SAFE parameters.	0
demo_params	bool	Use demo parameters.	True
safe_params	dict	Dictionary of SAFE parameters (see gropt.readasc).	None

Returns:

Type	Description
ndarray	SAFE response curve.

Eddy Currents

Problem definition for GrOpt gradient optimization.

This class holds the waveform dimensions, constraints, and objectives that define a gradient optimization problem.

add_eddy

add_eddy(lam: object, tol: float = 0.0001, weight_mod: float = 1.0) -> None

Add an eddy current constraint.

Parameters:

Name	Type	Description	Default
lam	float or ndarray	Time constant(s) for eddy currents [seconds]. A single float is treated as a one-element array.	required
tol	float	Tolerance for the constraint.	0.0001
weight_mod	float	Weighting factor for this constraint.	1.0

Concomitant Fields

Problem definition for GrOpt gradient optimization.

This class holds the waveform dimensions, constraints, and objectives that define a gradient optimization problem.

add_concomitant

add_concomitant(start_idx: int = 0, rot_variant: bool = True, weight_mod: float = 1.0) -> None

Add a concomitant constraint.

Parameters:

Name	Type	Description	Default
start_idx	int	Starting index for the constraint (-1 = beginning).	0
rot_variant	bool	If True, use rotationally invariant formulation.	True
weight_mod	float	Weighting factor for this constraint.	1.0

Total Variation

Problem definition for GrOpt gradient optimization.

This class holds the waveform dimensions, constraints, and objectives that define a gradient optimization problem.

add_TV

add_TV(tv_lam: float = 0.0, weight_mod: float = 1.0) -> None

Add total variation regularization.

Parameters:

Name	Type	Description	Default
tv_lam	float	Regularization strength (must be > 0 to have effect).	0.0
weight_mod	float	Weighting factor.	1.0

Objectives

Problem definition for GrOpt gradient optimization.

This class holds the waveform dimensions, constraints, and objectives that define a gradient optimization problem.

add_obj_identity

add_obj_identity(weight_mod: float = 1.0) -> None

Add an identity (L2 norm) objective.

Parameters:

Name	Type	Description	Default
weight_mod	float	Weighting factor.	1.0