openlifu.plan.protocol.Protocol

class openlifu.plan.protocol.Protocol(id: "Annotated[str, OpenLIFUFieldData('Protocol ID', 'The unique identifier of the protocol')]" = 'protocol', name: "Annotated[str, OpenLIFUFieldData('Protocol name', 'The name of the protocol')]" = 'Protocol', description: "Annotated[str, OpenLIFUFieldData('Protocol description', 'A more detailed description of the protocol')]" = '', allowed_roles: "Annotated[List[str], OpenLIFUFieldData('Allowed roles', 'A list of user roles allowed to interact with this protocol')]" = <factory>, pulse: "Annotated[bf.Pulse, OpenLIFUFieldData('Pulse definition', 'The pulse definition used in the protocol')]" = <factory>, sequence: "Annotated[bf.Sequence, OpenLIFUFieldData('Pulse sequence', 'The sequence of pulses used in the protocol')]" = <factory>, focal_pattern: "Annotated[bf.FocalPattern, OpenLIFUFieldData('Focal pattern', 'The focal pattern used in the protocol. By default, a single point is used')]" = <factory>, sim_setup: "Annotated[sim.SimSetup, OpenLIFUFieldData('Simulation setup', 'Configuration options for using k-wave to simulate wave propagation')]" = <factory>, delay_method: "Annotated[bf.DelayMethod, OpenLIFUFieldData('Delay method', 'The method used to calculate transmit delays. By default, delays are calculated using a nominal speed of sound')]" = <factory>, apod_method: "Annotated[bf.ApodizationMethod, OpenLIFUFieldData('Apodization method', 'The method used to calculate transmit apodizations. By default, apodizations are uniform')]" = <factory>, seg_method: 'Annotated[seg.SegmentationMethod, OpenLIFUFieldData(\'Segmentation method\', "The method used to segment the subject\'s MRI for delay calculation. By default, the entire field is assumed to be water")]' = <factory>, param_constraints: "Annotated[dict, OpenLIFUFieldData('Parameter constraints', 'The constraints on the analysis parameters. If computed parameters are outside of the ranges defined here, warnings or errors may be flagged to reject the solution')]" = <factory>, target_constraints: "Annotated[List[TargetConstraints], OpenLIFUFieldData('Target constraints', 'The constraints on the target position. If the target is outside of the bounds defined here, warnings or errors may be flagged to reject the solution')]" = <factory>, analysis_options: "Annotated[SolutionAnalysisOptions, OpenLIFUFieldData('Analysis options', 'Options to adjust solution analysis. By default, the analysis is configured with default options')]" = <factory>, virtual_fit_options: "Annotated[VirtualFitOptions, OpenLIFUFieldData('Virtual fit options', 'Configuration of the virtual fit algorithm')]" = <factory>)[source]

Bases: object

allowed_roles: Annotated[List[str], OpenLIFUFieldData(name='Allowed roles', description='A list of user roles allowed to interact with this protocol')]

A list of user roles allowed to interact with this protocol

analysis_options: Annotated[SolutionAnalysisOptions, OpenLIFUFieldData(name='Analysis options', description='Options to adjust solution analysis. By default, the analysis is configured with default options')]

Options to adjust solution analysis. By default, the analysis is configured with default options

apod_method: Annotated[ApodizationMethod, OpenLIFUFieldData(name='Apodization method', description='The method used to calculate transmit apodizations. By default, apodizations are uniform')]

The method used to calculate transmit apodizations. By default, apodizations are uniform

calc_solution(target: Point, transducer: Transducer, volume: DataArray | None = None, params: Dataset | None = None, session: Session | None = None, simulate: bool = True, scale: bool = True, sim_options: SimSetup | None = None, analysis_options: SolutionAnalysisOptions | None = None, on_pulse_mismatch: OnPulseMismatchAction = OnPulseMismatchAction.ERROR, voltage: float = 1.0, _force_cpu: bool = False) → Tuple[Solution, DataArray, SolutionAnalysis][source]

Calculate the solution and aggregated k-wave simulation outputs.

Method that computes the delays and apodizations for each focus in the treatment plan, simulates the resulting pressure field to adjust transmit pressures to reach target pressures, and then analyzes the resulting pressure field to compute the resulting acoustic parameters.

Parameters:

  • target – The target Point. Target is expected to be in the simulation grid coordinates (lat, ele, ax).

  • transducer – A Transducer item.

  • volume – xa.DataArray The subject scan (Default: None). It is expected to be in the simulation grid coordinates (lat, ele, ax). If None, a default simulation grid will be used.

  • params –

    xa.Dataset | None = None The simulation parameters to use for the k-wave simulation (Default: None, which uses sim_options.setup_sim_scene on the volume). If the params are provided, the volume is not required. Params should include xa.DataArrays for the following:

    ’sound_speed’: speed of sound in the medium (m/s) ‘density’: density of the medium (kg/m^3) ‘attenuation’: attenuation coefficient of the medium (dB/cm/MHz) and can also include (though they aren’t used in the simulation) ‘specific_heat’: specific heat capacity of the medium (J/kg/K) ‘thermal_conductivity’: thermal conductivity of the medium (W/m/K)

  • session – Session | None = None the current session object (used for assigning a matching solution ID only)

  • simulate – bool Enable solution simulation (Default: true).

  • scale – bool Triggers solution and simulation scaling to the requested pressure (Default: true).

  • sim_options – sim.SimSetup The options for the k-wave simulation (Default: self.sim_setup).

  • analysis_options – plan.solution.SolutionAnalysisOptions The options for the solution analysis (Default: self.analysis_options).

  • on_pulse_mismatch – plan.protocol.OnPulseMismatchAction An action to take if the number of pulses in the sequence does not match the number of foci (Default: OnPulseMismatchAction.ERROR).

  • voltage – float The voltage to use for the simulation (Default: 1.0).

  • _force_cpu – bool If True, force the simulation to run on CPU even if GPU is available (Default: False).

Returns:

Solution simulation_result_aggregated: xa.Dataset

If simulation is enabled, then this is the resulting aggregated output (max pressure and mean intensity over all foci).

scaled_solution_analysis: SolutionAnalysis

This is the resulting rescaled analysis, if scale is enabled.

Return type:

solution

check_target(target: Point)[source]

Check if a target is within bounds, raising an exception if it isn’t.

Parameters:

target – The geo.Point target to check.

delay_method: Annotated[DelayMethod, OpenLIFUFieldData(name='Delay method', description='The method used to calculate transmit delays. By default, delays are calculated using a nominal speed of sound')]

The method used to calculate transmit delays. By default, delays are calculated using a nominal speed of sound

description: Annotated[str, OpenLIFUFieldData(name='Protocol description', description='A more detailed description of the protocol')] = ''

A more detailed description of the protocol

fix_pulse_mismatch(on_pulse_mismatch: OnPulseMismatchAction, foci: List[Point])[source]

Fix the protocol sequence pulse count in-place given a pulse_mismatch action.

focal_pattern: Annotated[FocalPattern, OpenLIFUFieldData(name='Focal pattern', description='The focal pattern used in the protocol. By default, a single point is used')]

The focal pattern used in the protocol. By default, a single point is used

static from_json(json_string: str) → Protocol[source]

Load a Protocol from a json string

id: Annotated[str, OpenLIFUFieldData(name='Protocol ID', description='The unique identifier of the protocol')] = 'protocol'

The unique identifier of the protocol

name: Annotated[str, OpenLIFUFieldData(name='Protocol name', description='The name of the protocol')] = 'Protocol'

The name of the protocol

param_constraints: Annotated[dict, OpenLIFUFieldData(name='Parameter constraints', description='The constraints on the analysis parameters. If computed parameters are outside of the ranges defined here, warnings or errors may be flagged to reject the solution')]

The constraints on the analysis parameters. If computed parameters are outside of the ranges defined here, warnings or errors may be flagged to reject the solution

pulse: Annotated[Pulse, OpenLIFUFieldData(name='Pulse definition', description='The pulse definition used in the protocol')]

The pulse definition used in the protocol

seg_method: Annotated[SegmentationMethod, OpenLIFUFieldData(name='Segmentation method', description="The method used to segment the subject's MRI for delay calculation. By default, the entire field is assumed to be water")]

The method used to segment the subject’s MRI for delay calculation. By default, the entire field is assumed to be water

sequence: Annotated[Sequence, OpenLIFUFieldData(name='Pulse sequence', description='The sequence of pulses used in the protocol')]

The sequence of pulses used in the protocol

sim_setup: Annotated[SimSetup, OpenLIFUFieldData(name='Simulation setup', description='Configuration options for using k-wave to simulate wave propagation')]

Configuration options for using k-wave to simulate wave propagation

target_constraints: Annotated[List[TargetConstraints], OpenLIFUFieldData(name='Target constraints', description='The constraints on the target position. If the target is outside of the bounds defined here, warnings or errors may be flagged to reject the solution')]

The constraints on the target position. If the target is outside of the bounds defined here, warnings or errors may be flagged to reject the solution

to_file(filename: str)[source]

Save the protocol to a file

Parameters:

filename – Name of the file

to_json(compact: bool) → str[source]

Serialize a Protocol to a json string

Parameters:

compact – if enabled then the string is compact (not pretty). Disable for pretty.

Returns: A json string representing the complete Protocol object.

to_table() → DataFrame[source]

Return a table of the most important protocol parameters

Example output:

` Category      Name            Value Unit 0              ID             example_protocol 1            Name             Example protocol 2           Description  Example protocol created 30-Jan-2024 09:16:02 3       Pulse       Frequency               500000.0   Hz 4       Pulse       Amplitude              1.0   AU 5       Pulse        Duration          0.00002    s 6    Sequence  Pulse Interval              0.1    s `

virtual_fit_options: Annotated[VirtualFitOptions, OpenLIFUFieldData(name='Virtual fit options', description='Configuration of the virtual fit algorithm')]

Configuration of the virtual fit algorithm