openlifu.plan.solution.Solution

class openlifu.plan.solution.Solution(id: ~typing.Annotated[str, OpenLIFUFieldData(name='Solution ID', description='ID of this solution')] = 'solution', name: ~typing.Annotated[str, OpenLIFUFieldData(name='Solution name', description='Name of this solution')] = 'Solution', protocol_id: ~typing.Annotated[str | None, OpenLIFUFieldData(name='Protocol ID', description='ID of the protocol that was used when generating this solution')] = None, transducer: ~typing.Annotated[~openlifu.xdc.transducer.Transducer | None, OpenLIFUFieldData(name='Transducer', description='Transducer used when generating this solution')] = None, date_created: ~typing.Annotated[~datetime.datetime, OpenLIFUFieldData(name='Creation date', description='Solution creation time')] = <factory>, description: ~typing.Annotated[str, OpenLIFUFieldData(name='Description', description='Description of this solution')] = '', delays: ~typing.Annotated[~numpy.ndarray | None, OpenLIFUFieldData(name='Delays', description='Vectors of time delays to steer the beam. Shape is (number of foci, number of transducer elements).')] = None, apodizations: ~typing.Annotated[~numpy.ndarray | None, OpenLIFUFieldData(name='Apodizations', description='Vectors of apodizations to steer the beam. Shape is (number of foci, number of transducer elements).')] = None, pulse: ~typing.Annotated[~openlifu.bf.pulse.Pulse, OpenLIFUFieldData(name='Pulse', description='Pulse to send to the transducer when running sonication')] = <factory>, voltage: ~typing.Annotated[float, OpenLIFUFieldData(name='Voltage', description='Voltage to use when running sonication. This is the voltage that will be set on the HV power supply.')] = 1.0, sequence: ~typing.Annotated[~openlifu.bf.sequence.Sequence, OpenLIFUFieldData(name='Pulse sequence', description='Pulse sequence to use when running sonication')] = <factory>, foci: ~typing.Annotated[~typing.List[~openlifu.geo.Point], OpenLIFUFieldData(name='Foci', description='Points that are focused on in this Solution due to the focal pattern around the target. Each item in this list is a unique point from the focal pattern, and the pulse sequence is what determines how many times each point will be used.')] = <factory>, target: ~typing.Annotated[~openlifu.geo.Point | None, OpenLIFUFieldData(name='Target point', description='The ultimate target of this sonication. This sonication solution is focused on one focal point in a pattern that is centered on this target.')] = None, simulation_result: ~typing.Annotated[~xarray.core.dataset.Dataset, OpenLIFUFieldData(name='Simulation result', description='The xarray Dataset of simulation results')] = <factory>, approved: ~typing.Annotated[bool, OpenLIFUFieldData(name='Approved?', description='Approval state of this solution as a sonication plan. `True` means the user has provided some kind of confirmation that the solution is safe and acceptable to be executed.')] = False)

Bases: object

A sonication solution resulting from beamforming and running a simulation.

analyze(simulation_result: Dataset | None = None, options: SolutionAnalysisOptions = SolutionAnalysisOptions(standoff_sound_speed=1500.0, standoff_density=1000.0, ref_sound_speed=1500.0, ref_density=1000.0, mainlobe_aspect_ratio=(1.0, 1.0, 5.0), mainlobe_radius=0.0025, beamwidth_radius=0.005, sidelobe_radius=0.003, sidelobe_zmin=0.001, distance_units='m', param_constraints={}), param_constraints: Dict[str, ParameterConstraint] | None = None) → SolutionAnalysis

Analyzes the treatment solution.

Parameters:

• simulation_result – The simulation result dataset to analyze. If None, uses self.simulation_result.

• options – A struct for solution analysis options.

• param_constraints – A dictionary of parameter constraints to apply to the analysis. The keys are the parameter names and the values are the ParameterConstraint objects.

Returns: A struct containing the results of the analysis.

apodizations: Annotated[ndarray | None, OpenLIFUFieldData(name='Apodizations', description='Vectors of apodizations to steer the beam. Shape is (number of foci, number of transducer elements).')] = None

Vectors of apodizations to steer the beam. Shape is (number of foci, number of transducer elements).

approved: Annotated[bool, OpenLIFUFieldData(name='Approved?', description='Approval state of this solution as a sonication plan. `True` means the user has provided some kind of confirmation that the solution is safe and acceptable to be executed.')] = False

Approval state of this solution as a sonication plan. True means the user has provided some kind of confirmation that the solution is safe and acceptable to be executed.

compute_scaling_factors(focal_pattern: FocalPattern, analysis: SolutionAnalysis) → Tuple[ndarray, float, float]

Compute the scaling factors used to re-scale the apodizations, simulation results and pulse amplitude.

Parameters:

• focal_pattern – FocalPattern

• analysis – SolutionAnalysis

Returns:

A np.ndarray apodization factors v0: A float representing the original pulse amplitude v1: A float representing the new pulse amplitude

Return type:

apod_factors

date_created: Annotated[datetime, OpenLIFUFieldData(name='Creation date', description='Solution creation time')]

Solution creation time

delays: Annotated[ndarray | None, OpenLIFUFieldData(name='Delays', description='Vectors of time delays to steer the beam. Shape is (number of foci, number of transducer elements).')] = None

Vectors of time delays to steer the beam. Shape is (number of foci, number of transducer elements).

description: Annotated[str, OpenLIFUFieldData(name='Description', description='Description of this solution')] = ''

Description of this solution

estimate_tx_temperature_rise(t_sec: float, T0_degC: float = 30.0)

Standalone temperature prediction function for thermal modeling.

Based on physics-based power decay gradient model fitted from experimental data. Model: dT/dt = (t + t_shift)^(-n) + C

Parameters:

self: Solution

The treatment solution containing voltage and pulse information.

t_sec: float

Time in seconds for which to predict temperature rise.

T0_degC: float

Initial temperature in Celsius. Default is 30.0°C.

Returns:

float

Predicted temperature rise in Celsius

foci: Annotated[List[Point], OpenLIFUFieldData(name='Foci', description='Points that are focused on in this Solution due to the focal pattern around the target. Each item in this list is a unique point from the focal pattern, and the pulse sequence is what determines how many times each point will be used.')]

Points that are focused on in this Solution due to the focal pattern around the target. Each item in this list is a unique point from the focal pattern, and the pulse sequence is what determines how many times each point will be used.

static from_dict(solution_dict: dict) → Solution

Load a Solution from a dictionary.

Parameters:

solution_dict – The dictionary containing the solution data.

Returns: The new Solution object.

static from_files(json_filepath: Path, nc_filepath: Path | None = None)

Read solution from json and netCDF files.

json_filepath: solution json file location, containing all data except the simulation results dataset nc_filepath: netCDF file location, containing the simulation results.

If None then it will be assumed to be saved in the same directory as the json file, with the same name but with the extension *.nc. This is the default saving behavior of Solution.to_files.

static from_json(json_string: str, simulation_result: Dataset | None = None) → Solution

Load a Solution from a json string.

Parameters:

• json_string – the json string defining the Solution

• simulation_result – the simulation result arrays to use. If the json string has this then it will be read from the json string and it should not be provided in this argument.

Returns: The new Solution object.

get_ita(intensity: DataArray | None = None, units: str = 'mW/cm^2') → DataArray

Calculate the intensity-time-area product for a treatment solution.

Parameters:

• intensity – xa.DataArray | None If provided, use this intensity data array instead of the one from the simulation result.

• units – str Target units. Default “mW/cm^2”.

Returns:

xa.DataArray

The intensity-time-area product as an xarray DataArray.

get_pulsetrain_dutycycle() → float

Compute the pulse train dutycycle given a sequence.

Returns:

A float.

get_sequence_dutycycle() → float

Compute the overall sequence dutycycle given a sequence.

Returns:

A float.

id: Annotated[str, OpenLIFUFieldData(name='Solution ID', description='ID of this solution')] = 'solution'

ID of this solution

name: Annotated[str, OpenLIFUFieldData(name='Solution name', description='Name of this solution')] = 'Solution'

Name of this solution

num_foci() → int

Get the number of foci

protocol_id: Annotated[str | None, OpenLIFUFieldData(name='Protocol ID', description='ID of the protocol that was used when generating this solution')] = None

ID of the protocol that was used when generating this solution

pulse: Annotated[Pulse, OpenLIFUFieldData(name='Pulse', description='Pulse to send to the transducer when running sonication')]

Pulse to send to the transducer when running sonication

scale(focal_pattern: FocalPattern, analysis_options: SolutionAnalysisOptions = SolutionAnalysisOptions(standoff_sound_speed=1500.0, standoff_density=1000.0, ref_sound_speed=1500.0, ref_density=1000.0, mainlobe_aspect_ratio=(1.0, 1.0, 5.0), mainlobe_radius=0.0025, beamwidth_radius=0.005, sidelobe_radius=0.003, sidelobe_zmin=0.001, distance_units='m', param_constraints={})) → None

Scale the solution in-place to match the target pressure.

Parameters:

• focal_pattern – FocalPattern

• analysis_options – plan.solution.SolutionAnalysisOptions

Returns:

the resulting plan.solution.SolutionAnalysis from scaled solution

Return type:

analysis_scaled

sequence: Annotated[Sequence, OpenLIFUFieldData(name='Pulse sequence', description='Pulse sequence to use when running sonication')]

Pulse sequence to use when running sonication

simulate(params: Dataset, sim_options: SimSetup | None = None, _force_cpu: bool = False) → Dataset

Run a simulation for this solution and store the result in the simulation_result attribute.

Parameters:

• params – The simulation parameters as an xarray Dataset.

• sim_options – Optional simulation setup options.

• _force_cpu – Whether to force the simulation to run on the CPU. If True, the GPU will not be used even if available.

Returns:

The simulation result as an xarray Dataset.

simulation_result: Annotated[Dataset, OpenLIFUFieldData(name='Simulation result', description='The xarray Dataset of simulation results')]

The xarray Dataset of simulation results

target: Annotated[Point | None, OpenLIFUFieldData(name='Target point', description='The ultimate target of this sonication. This sonication solution is focused on one focal point in a pattern that is centered on this target.')] = None

The ultimate target of this sonication. This sonication solution is focused on one focal point in a pattern that is centered on this target.

to_dict(include_simulation_data: bool = False) → dict

Serialize a Solution to a dictionary

Parameters:

include_simulation_data – if enabled then large simulation data arrays are included in the dict, otherwise they are excluded.

Returns: A dictionary representing the complete Solution object.

to_files(json_filepath: Path, nc_filepath: Path | None = None) → None

Save the solution to json and netCDF files.

json_filepath: where to save the json file with all data except the simulation results dataset nc_filepath: where to save the netCDF file containing the simulation results.

If None then it will be saved in the same directory as the json file, with the same name but with the extension *.nc

to_json(include_simulation_data: bool, compact: bool) → str

Serialize a Solution to a json string

Parameters:

• include_array_data – if enabled then large simulation data arrays are serialized somehow into the json, so that they can be recovered via from_json alone. otherwise they are excluded.

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

Returns: A json string representing the complete Solution object.

transducer: Annotated[Transducer | None, OpenLIFUFieldData(name='Transducer', description='Transducer used when generating this solution')] = None

Transducer used when generating this solution

voltage: Annotated[float, OpenLIFUFieldData(name='Voltage', description='Voltage to use when running sonication. This is the voltage that will be set on the HV power supply.')] = 1.0

Voltage to use when running sonication. This is the voltage that will be set on the HV power supply.