optimization

pyRadPlan.optimization

Treatment plan optimization algorithms and objectives.

class Objective(**data)

Bases: PyRadPlanBaseModel

Base class for objective functions in the optimization problem.

name

Name of the objective function.

Type:

ClassVar[str]

has_hessian

Whether the objective function has a Hessian implementation.

Type:

ClassVar[bool]

priority

Weight/Priority assigned to the objective function.

Type:

float

quantity

The quantity this objective is connected to (e.g. ‘physical_dose’, ‘RBExDose’).

Type:

str

Attributes:

model_extra

Get extra fields set during validation.

model_fields_set

Returns the set of fields that have been explicitly set on this model instance.

parameter_names

List[str]: Parameter names.

parameter_types

List[str]: Parameter types.

parameters

List[str]: Parameter values.

Methods

compute_gradient(values)	Compute the objective gradient.
compute_hessian(values)	Compute the objective Hessian.
compute_objective(values)	Compute the objective function.
copy(*[, include, exclude, update, deep])	Returns a copy of the model.
model_construct([_fields_set])	Creates a new instance of the Model class with validated data.
model_copy(*[, update, deep])	!!! abstract "Usage Documentation"
model_dump(*[, mode, include, exclude, ...])	!!! abstract "Usage Documentation"
model_dump_json(*[, indent, ensure_ascii, ...])	!!! abstract "Usage Documentation"
model_json_schema([by_alias, ref_template, ...])	Generates a JSON schema for a model class.
model_parametrized_name(params)	Compute the class name for parametrizations of generic classes.
model_post_init(context, /)	This function is meant to behave like a BaseModel method to initialize private attributes.
model_rebuild(*[, force, raise_errors, ...])	Try to rebuild the pydantic-core schema for the model.
model_validate(obj, *[, strict, extra, ...])	Validate a pydantic model instance.
model_validate_json(json_data, *[, strict, ...])	!!! abstract "Usage Documentation"
model_validate_strings(obj, *[, strict, ...])	Validate the given object with string data against the Pydantic model.
preprocess_image_reference_parameters(...[, ...])	Preprocess image reference parameters if existing in the objective definition.
to_matrad([context])	Perform matRad compatible serialization.

construct
dict
from_orm
json
parse_file
parse_obj
parse_raw
schema
schema_json
update_forward_refs
validate

abstractmethod compute_gradient(values)

Compute the objective gradient.

compute_hessian(values)

Compute the objective Hessian.

abstractmethod compute_objective(values)

Compute the objective function.

has_hessian: ClassVar[bool] = False

model_config: ClassVar[ConfigDict] = {'alias_generator': AliasGenerator(alias=<function to_camel>, validation_alias=None, serialization_alias=None), 'arbitrary_types_allowed': True, 'from_attributes': True, 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.

Return type:

None

name: ClassVar[str]

property parameter_names: list[str]

Parameter names.

Type:

List[str]

property parameter_types: list[Literal['reference', 'numeric', 'relative_volume', 'image_reference'] | list[str]]

Parameter types.

Type:

List[str]

property parameters: list[Any]

Parameter values.

Type:

List[str]

preprocess_image_reference_parameters(target_grid, index_list=None)

Preprocess image reference parameters if existing in the objective definition.

Preprocessing of reference image parameters is necessary to align with the corresponding target dose/optimization grid. The function will resample the reference image to the target grid and cache it.

Parameters:

• target_grid (Grid) – The target grid that the parameter should match.

• index_list (Optional[ArrayType]) – Array containing indices for which the objective needs to be cached

priority: float

quantity: str

fluence_optimization(ct, cst, stf, dij, pln)

Trigger fluence optimization using the configuration stored in the pln object.

Parameters:

• ct (CT) – CT object.

• cst (StructureSet) – StructureSet object.

• stf (SteeringInformation) – SteeringInformation object.

• dij (Dij) – Dij object.

• pln (Plan) – Plan object.

Returns:

The optimized fluence map.

Return type:

ndarray

Components

Optimization solvers for treatment planning problems.

class NonLinearOptimizer

Bases: SolverBase

Non-Linear Optimization Solver Base Class.

max_iter

Maximum number of iterations

Type:

int

abs_obj_tol

Absolute objective tolerance

Type:

float

objective

Objective function handle

Type:

Callable

gradient

Gradient function handle

Type:

Callable

hessian

Hessian function handle

Type:

Callable, default=None

constraints

Constraints function handle

Type:

Callable, default=None

constraints_jac

Constraints Jacobian function handle

Type:

Callable, default=None

supply_iter_func

Whether to supply an iteration callback function

Type:

bool

Methods

iter_func(*args, **kwargs)	Get or set solver information as iteration callback.
solve(x0)	Interface method to solve the problem.

gpu_compatible
name
short_name

abs_obj_tol: float

constraints: Callable

constraints_jac: Callable

gradient: Callable

hessian: Callable

iter_func(*args, **kwargs)

Get or set solver information as iteration callback.

Agnostic signature with *args and **kwargs to be able to accommodate various solvers.

Parameters:

• *args – Additional arguments

• **kwargs – Additional keyword arguments

Returns:

Whether to continue the optimization

Return type:

bool

max_iter: int

objective: Callable

supply_iter_func: bool

class OptimizerSciPy

Bases: NonLinearOptimizer

SciPy solver configuration class.

options

Options for the solver

Type:

dict

method

The solver method

Type:

Union[str, Callable]

Methods

iter_func(*args, **kwargs)	Get or set solver information as iteration callback.
solve(x0)	Interface method to solve the problem.

allow_keyboard_cancel: bool = True

gpu_compatible = False

method: str | Callable

name = 'SciPy minimize'

options: dict[str]

short_name = 'scipy'

class SolverBase

Bases: ABC

Abstract Base Class for Solver Implementations / Interfaces.

name

Full name of the solver

Type:

ClassVar[str]

short_name

Short name of the solver

Type:

ClassVar[str]

max_time

Maximum time for the solver to run in seconds

Type:

float, default=3600

bounds

Bounds for the variables

Type:

Array, default=[0.0, np.inf]

Methods

solve(x0)

Interface method to solve the problem.

gpu_compatible
name
short_name

allow_esc_cancel: bool = True

allow_keyboard_cancel: bool = False

bounds: Annotated[ArrayType, ArrayAPIArray]

cancel_key: str = 'q'

gpu_compatible

alias of ClassVar[bool]

max_time: float

name

alias of ClassVar[str]

short_name

alias of ClassVar[str]

solve(x0)

Interface method to solve the problem.

Parameters:

x0 (ArrayType) – Initial guess for the solution

Returns:

Solution vector and additional information as dictionary

Return type:

tuple[ArrayType, dict]

get_available_solvers()

Get a list of available solvers based on the plan.

Returns:

A list of available solvers.

Return type:

dict[str, Type[SolverBase]]

get_solver(solver_desc)

Return a solver instance based on a descriptive parameter.

Parameters:

solver_desc (Union[str, dict, SolverBase]) – A string with the solver name, a dictionary with the solver configuration or a solver instance

Returns:

A solver instance

Return type:

SolverBase

register_solver(solver_cls)

Register a new solver.

Parameters:

solver_cls (Type[SolverBase]) – A Dose Solver class.

Return type:

None