dival.reconstructors package¶
Subpackages¶
Submodules¶
- dival.reconstructors.dip_ct_reconstructor module
- dival.reconstructors.fbpunet_reconstructor module
- dival.reconstructors.iradonmap_reconstructor module
- dival.reconstructors.learnedgd_reconstructor module
- dival.reconstructors.learnedpd_reconstructor module
- dival.reconstructors.odl_reconstructors module
- dival.reconstructors.reconstructor module
- dival.reconstructors.regression_reconstructors module
- dival.reconstructors.standard_learned_reconstructor module
- dival.reconstructors.tvadam_ct_reconstructor module
Module contents¶
-
class
dival.reconstructors.
Reconstructor
(reco_space=None, observation_space=None, name='', hyper_params=None)[source]¶ Bases:
object
Abstract reconstructor base class.
There are two ways of implementing a Reconstructor subclass:
Implement
reconstruct()
. It has to support optional in-place and out-of-place evaluation.Implement
_reconstruct()
. It must have one of the following signatures:_reconstruct(self, observation, out)
(in-place)_reconstruct(self, observation)
(out-of-place)_reconstruct(self, observation, out=None)
(optional in-place)
The class attribute
HYPER_PARAMS
defines the hyper parameters of the reconstructor class. The current values for a reconstructor instance are given by the attributehyper_params
. Properties wrappinghyper_params
are automatically created by the metaclass (for hyper parameter names that are valid identifiers), such that the hyper parameters can be written and read like instance attributes.-
reco_space
¶ Reconstruction space.
- Type
odl.discr.DiscretizedSpace
, optional
-
observation_space
¶ Observation space.
- Type
odl.discr.DiscretizedSpace
, optional
-
name
¶ Name of the reconstructor.
- Type
str
-
hyper_params
¶ Current hyper parameter values. Initialized automatically using the default values from
HYPER_PARAMS
(but may be overridden by hyper_params passed to__init__()
). It is expected to have the same keys asHYPER_PARAMS
. The values for these keys in this dict are wrapped by properties with the key as identifier (if possible), so an assignment to the property changes the value in this dict and vice versa.- Type
dict
-
HYPER_PARAMS
= {}¶ Specification of hyper parameters.
This class attribute is a dict that lists the hyper parameter of the reconstructor. It should not be hidden by an instance attribute of the same name (i.e. by assigning a value to self.HYPER_PARAMS in an instance of a subtype).
Note: in order to inherit
HYPER_PARAMS
from a super class, the subclass should create a deep copy of it, i.e. executeHYPER_PARAMS = copy.deepcopy(SuperReconstructorClass.HYPER_PARAMS)
in the class body.The keys of this dict are the names of the hyper parameters, and each value is a dict with the following fields.
Standard fields:
'default'
Default value.
'retrain'
bool, optionalWhether training depends on the parameter. Default:
False
. Any custom subclass of LearnedReconstructor must set this field toTrue
if training depends on the parameter value.
Hyper parameter search fields:
'range'
(float, float), optionalInterval of valid values. If this field is set, the parameter is taken to be real-valued. Either
'range'
or'choices'
has to be set.'choices'
sequence, optionalSequence of valid values of any type. If this field is set,
'range'
is ignored. Can be used to perform manual grid search. Either'range'
or'choices'
has to be set.'method'
{‘grid_search’, ‘hyperopt’}, optionalOptimization method for the parameter. Default:
'grid_search'
. Options are:'grid_search'
Grid search over a sequence of fixed values. Can be configured by the dict
'grid_search_options'
.'hyperopt'
Random search using the
hyperopt
package. Can be configured by the dict'hyperopt_options'
.
'grid_search_options'
dictOption dict for grid search.
The following fields determine how
'range'
is sampled (in case it is specified and no'choices'
are specified):'num_samples'
int, optionalNumber of values. Default:
10
.'type'
{‘linear’, ‘logarithmic’}, optionalType of grid, i.e. distribution of the values. Default:
'linear'
. Options are:'linear'
Equidistant values in the
'range'
.'logarithmic'
Values in the
'range'
that are equidistant in the log scale.
'log_base'
int, optionalLog-base that is used if
'type'
is'logarithmic'
. Default:10.
.
'hyperopt_options'
dictOption dict for
'hyperopt'
method with the fields:'space'
hyperopt space, optionalCustom hyperopt search space. If this field is set,
'range'
and'type'
are ignored.'type'
{‘uniform’}, optionalType of the space for sampling. Default:
'uniform'
. Options are:'uniform'
Uniform distribution over the
'range'
.
-
__init__
(reco_space=None, observation_space=None, name='', hyper_params=None)[source]¶ Initialize self. See help(type(self)) for accurate signature.
-
reconstruct
(observation, out=None)[source]¶ Reconstruct input data from observation data.
The default implementation calls _reconstruct, automatically choosing in-place or out-of-place evaluation.
- Parameters
observation (
observation_space
element-like) – The observation data.out (
reco_space
element-like, optional) – Array to which the result is written (in-place evaluation). If None, a new array is created (out-of-place evaluation). If None, the new array is initialized with zero before calling_reconstruct()
.
- Returns
reconstruction – The reconstruction.
- Return type
reco_space
element or out
-
save_hyper_params
(path)[source]¶ Save hyper parameters to JSON file. See also
load_hyper_params()
.- Parameters
path (str) – Path of the file in which the hyper parameters should be saved. The ending
'.json'
is automatically appended if not included.
-
load_hyper_params
(path)[source]¶ Load hyper parameters from JSON file. See also
save_hyper_params()
.- Parameters
path (str) – Path of the file in which the hyper parameters are stored. The ending
'.json'
is automatically appended if not included.
-
save_params
(path=None, hyper_params_path=None)[source]¶ Save all parameters to file. E.g. for learned reconstructors, both hyper parameters and learned parameters should be included. The purpose of this method, together with
load_params()
, is to define a unified way of saving and loading any kind of reconstructor. The default implementation callssave_hyper_params()
. Subclasses must reimplement this method in order to include non-hyper parameters.Implementations should derive a sensible default for hyper_params_path from path, such that all parameters can be saved and loaded by specifying only path. Recommended patterns are:
if non-hyper parameters are stored in a single file and path specifies it without file ending:
hyper_params_path=path + '_hyper_params.json'
if non-hyper parameters are stored in a directory:
hyper_params_path=os.path.join(path, 'hyper_params.json')
.if there are no non-hyper parameters, this default implementation can be used:
hyper_params_path=path + '_hyper_params.json'
- Parameters
path (str[, optional]) – Path at which all (non-hyper) parameters should be saved. This argument is required if the reconstructor has non-hyper parameters or hyper_params_path is omitted. If the reconstructor has non-hyper parameters, the implementation may interpret it as a file path or as a directory path for multiple files (the dir should be created by this method if it does not exist). If the implementation expects a file path, it should accept it without file ending.
hyper_params_path (str, optional) – Path of the file in which the hyper parameters should be saved. The ending
'.json'
is automatically appended if not included. If not specified, it should be determined from path (see method description above). The default implementation saves to the filepath + '_hyper_params.json'
.
-
load_params
(path=None, hyper_params_path=None)[source]¶ Load of parameters from file. E.g. for learned reconstructors, both hyper parameters and learned parameters should be included. The purpose of this method, together with
save_params()
, is to define a unified way of saving and loading any kind of reconstructor. The default implementation callsload_hyper_params()
. Subclasses must reimplement this method in order to include non-hyper parameters.See
save_params()
for recommended patterns to derive a default hyper_params_path from path.- Parameters
path (str[, optional]) – Path at which all (non-hyper) parameters are stored. This argument is required if the reconstructor has non-hyper parameters or hyper_params_path is omitted. If the reconstructor has non-hyper parameters, the implementation may interpret it as a file path or as a directory path for multiple files. If the implementation expects a file path, it should accept it without file ending.
hyper_params_path (str, optional) – Path of the file in which the hyper parameters are stored. The ending
'.json'
is automatically appended if not included. If not specified, it should be determined from path (see description ofsave_params()
). The default implementation reads from the filepath + '_hyper_params.json'
.
-
class
dival.reconstructors.
IterativeReconstructor
(callback=None, **kwargs)[source]¶ Bases:
dival.reconstructors.reconstructor.Reconstructor
Iterative reconstructor base class. It is recommended to use
StandardIterativeReconstructor
as a base class for iterative reconstructors if suitable, which provides some default implementation.Subclasses must call
callback
after each iteration inself.reconstruct
. This is e.g. required by theevaluation
module.-
callback
¶ Callback to be called after each iteration.
- Type
odl.solvers.util.callback.Callback
or None
-
HYPER_PARAMS
= {'iterations': {'default': 100, 'retrain': False}}¶
-
__init__
(callback=None, **kwargs)[source]¶ - Parameters
callback (
odl.solvers.util.callback.Callback
, optional) – Callback to be called after each iteration.
-
reconstruct
(observation, out=None, callback=None)[source]¶ Reconstruct input data from observation data.
Same as
Reconstructor.reconstruct()
, but with additional optional callback parameter.- Parameters
observation (
observation_space
element-like) – The observation data.out (
reco_space
element-like, optional) – Array to which the result is written (in-place evaluation). If None, a new array is created (out-of-place evaluation).callback (
odl.solvers.util.callback.Callback
, optional) – Additional callback for this reconstruction that is temporarily composed withcallback
, i.e. also called after each iteration. If None, justcallback
is called.
- Returns
reconstruction – The reconstruction.
- Return type
reco_space
element or out
-
property
iterations
¶
-
-
class
dival.reconstructors.
StandardIterativeReconstructor
(x0=None, callback=None, **kwargs)[source]¶ Bases:
dival.reconstructors.reconstructor.IterativeReconstructor
Standard iterative reconstructor base class.
Provides a default implementation that only requires subclasses to implement
_compute_iterate()
and optionally_setup()
.-
x0
¶ Default initial value for the iterative reconstruction. Can be overridden by passing a different
x0
toreconstruct()
.- Type
reco_space
element-like or None
-
callback
¶ Callback that is called after each iteration.
- Type
odl.solvers.util.callback.Callback
or None
-
__init__
(x0=None, callback=None, **kwargs)[source]¶ - Parameters
x0 (
reco_space
element-like, optional) – Default initial value for the iterative reconstruction. Can be overridden by passing a differentx0
toreconstruct()
.callback (
odl.solvers.util.callback.Callback
, optional) – Callback that is called after each iteration.
-
reconstruct
(observation, out=None, x0=None, last_iter=0, callback=None)[source]¶ Reconstruct input data from observation data.
Same as
Reconstructor.reconstruct()
, but with additional options for iterative reconstructors.- Parameters
observation (
observation_space
element-like) – The observation data.out (
reco_space
element-like, optional) – Array to which the result is written (in-place evaluation). If None, a new array is created (out-of-place evaluation).x0 (
reco_space
element-like, optional) – Initial value for the iterative reconstruction. Overrides the attributex0
, which can be set when calling__init__()
. If bothx0
and this argument are None, the default implementation uses the value of out if called in-place, or zero if called out-of-place.last_iter (int, optional) – If x0 is the result of an iteration by this method, this can be used to specify the number of iterations so far. The number of iterations for the current call is
self.hyper_params['iterations'] - last_iter
.callback (
odl.solvers.util.callback.Callback
, optional) – Additional callback for this reconstruction that is temporarily composed withcallback
, i.e. also called after each iteration. If None, justcallback
is called.
- Returns
reconstruction – The reconstruction.
- Return type
reco_space
element or out
-
property
iterations
¶
-
-
class
dival.reconstructors.
LearnedReconstructor
(reco_space=None, observation_space=None, name='', hyper_params=None)[source]¶ Bases:
dival.reconstructors.reconstructor.Reconstructor
-
train
(dataset)[source]¶ Train the reconstructor with a dataset by adapting its parameters.
Should only use the training and validation data from dataset.
- Parameters
dataset (
Dataset
) – The dataset from which the training data should be used.
-
save_params
(path, hyper_params_path=None)[source]¶ Save all parameters to file.
Calls
save_hyper_params()
andsave_learned_params()
, wheresave_learned_params()
should be implemented by the subclass.This implementation assumes that path is interpreted as a single file name, preferably specified without file ending. If path is a directory, the subclass needs to reimplement this method in order to follow the recommended default value pattern:
hyper_params_path=os.path.join(path, 'hyper_params.json')
.- Parameters
path (str) – Path at which the learned parameters should be saved. Passed to
save_learned_params()
. If the implementation interprets it as a file path, it is preferred to exclude the file ending (otherwise the default value of hyper_params_path is suboptimal).hyper_params_path (str, optional) – Path of the file in which the hyper parameters should be saved. The ending
'.json'
is automatically appended if not included. If not specified, this implementation saves to the filepath + '_hyper_params.json'
.
-
load_params
(path, hyper_params_path=None)[source]¶ Load all parameters from file.
Calls
load_hyper_params()
andload_learned_params()
, whereload_learned_params()
should be implemented by the subclass.This implementation assumes that path is interpreted as a single file name, preferably specified without file ending. If path is a directory, the subclass needs to reimplement this method in order to follow the recommended default value pattern:
hyper_params_path=os.path.join(path, 'hyper_params.json')
.- Parameters
path (str) – Path at which the parameters are stored. Passed to
load_learned_params()
. If the implementation interprets it as a file path, it is preferred to exclude the file ending (otherwise the default value of hyper_params_path is suboptimal).hyper_params_path (str, optional) – Path of the file in which the hyper parameters are stored. The ending
'.json'
is automatically appended if not included. If not specified, this implementation reads from the filepath + '_hyper_params.json'
.
-
save_learned_params
(path)[source]¶ Save learned parameters to file.
- Parameters
path (str) – Path at which the learned parameters should be saved. Implementations may interpret this as a file path or as a directory path for multiple files (which then should be created if it does not exist). If the implementation expects a file path, it should accept it without file ending.
-
load_learned_params
(path)[source]¶ Load learned parameters from file.
- Parameters
path (str) – Path at which the learned parameters are stored. Implementations may interpret this as a file path or as a directory path for multiple files. If the implementation expects a file path, it should accept it without file ending.
-
-
class
dival.reconstructors.
FunctionReconstructor
(function, *args, fun_args=None, fun_kwargs=None, **kwargs)[source]¶ Bases:
dival.reconstructors.reconstructor.Reconstructor
Reconstructor defined by a callable.
-
function
¶ Callable that is used in reconstruct.
- Type
callable
-
fun_args
¶ Arguments to be passed to function.
- Type
list
-
fun_kwargs
¶ Keyword arguments to be passed to function.
- Type
dict
-
-
class
dival.reconstructors.
StandardLearnedReconstructor
(op, hyper_params=None, num_data_loader_workers=8, use_cuda=True, show_pbar=True, log_dir=None, log_num_validation_samples=0, save_best_learned_params_path=None, torch_manual_seed=1, shuffle='auto', worker_init_fn=None, **kwargs)[source]¶ Bases:
dival.reconstructors.reconstructor.LearnedReconstructor
Standard learned reconstructor base class.
Provides a default implementation that only requires subclasses to implement
init_model()
.By default, the Adam optimizer is used. This can be changed by reimplementing
init_optimizer()
. Also, a OneCycleLR scheduler is used by default, which can be changed by reimplementinginit_scheduler()
.The training implementation selects the best model reached after an integer number of epochs based on the validation set.
The hyper parameter
'normalize_by_opnorm'
selects whetherop
should be normalized by the operator norm. In this case, the inputs tomodel
are divided by the operator norm.-
model
¶ The neural network. Must be initialized by the subclass
init_model()
implementation.- Type
torch.nn.Module
or None
-
non_normed_op
¶ The original op passed to
__init__()
, regardless ofself.hyper_params['normalize_by_opnorm']
. See alsoop
.- Type
odl.operator.Operator
-
HYPER_PARAMS
= {'batch_size': {'default': 64, 'retrain': True}, 'epochs': {'default': 20, 'retrain': True}, 'lr': {'default': 0.01, 'retrain': True}, 'normalize_by_opnorm': {'default': False, 'retrain': True}}¶
-
__init__
(op, hyper_params=None, num_data_loader_workers=8, use_cuda=True, show_pbar=True, log_dir=None, log_num_validation_samples=0, save_best_learned_params_path=None, torch_manual_seed=1, shuffle='auto', worker_init_fn=None, **kwargs)[source]¶ - Parameters
op (
odl.operator.Operator
) – Forward operator.num_data_loader_workers (int, optional) – Number of parallel workers to use for loading data.
use_cuda (bool, optional) – Whether to use cuda for the U-Net.
show_pbar (bool, optional) – Whether to show tqdm progress bars during the epochs.
log_dir (str, optional) – Tensorboard log directory (name of sub-directory in utils/logs). If None, no logs are written.
log_num_valiation_samples (int, optional) – Number of validation images to store in tensorboard logs. This option only takes effect if
log_dir is not None
.save_best_learned_params_path (str, optional) – Save best model weights during training under the specified path by calling
save_learned_params()
.torch_manual_seed (int, optional) – Fixed seed to set by
torch.manual_seed
before training. The default is 1. It can be set to None or False to disable the manual seed.shuffle ({
'auto'
,False
,True
}, optional) – Whether to use shuffling when loading data. When'auto'
is specified (the default),True
is used iff the dataset passed totrain()
supports random access.worker_init_fn (callable, optional) – Callable worker_init_fn passed to
torch.utils.data.DataLoader.__init__()
, which can be used to configure the dataset copies for different worker instances (cf. torch’s IterableDataset docs)
-
property
opnorm
¶
-
property
op
¶ odl.operator.Operator
: The forward operator, normalized ifself.hyper_params['normalize_by_opnorm']
isTrue
.
-
train
(dataset)[source]¶ Train the reconstructor with a dataset by adapting its parameters.
Should only use the training and validation data from dataset.
- Parameters
dataset (
Dataset
) – The dataset from which the training data should be used.
-
init_transform
(dataset)[source]¶ Initialize the transform (
_transform
) that is applied on each training sample, e.g. for data augmentation. In the default implementation oftrain()
, it is passed toDataset.create_torch_dataset()
when creating the training (but not the validation) torch dataset, which applies the transform to the (tuple of) torch tensor(s) right before returning, i.e. after reshaping to(1,) + orig_shape
.The default implementation of this method disables the transform by assigning None. Called in
train()
at the beginning, i.e. before callinginit_model()
,init_optimizer()
andinit_scheduler()
.- Parameters
dataset (
dival.datasets.dataset.Dataset
) – The dival dataset passed totrain()
.
-
property
transform
¶ callable: Transform that is applied on each sample, usually set by
init_transform()
, which gets called intrain()
.
-
init_model
()[source]¶ Initialize
model
. Called intrain()
after callinginit_transform()
, but before callinginit_optimizer()
andinit_scheduler()
.
-
init_optimizer
(dataset_train)[source]¶ Initialize the optimizer. Called in
train()
, after callinginit_transform()
andinit_model()
, but before callinginit_scheduler()
.- Parameters
dataset_train (
torch.utils.data.Dataset
) – The training (torch) dataset constructed intrain()
.
-
property
optimizer
¶ torch.optim.Optimizer
: The optimizer, usually set byinit_optimizer()
, which gets called intrain()
.
-
init_scheduler
(dataset_train)[source]¶ Initialize the learning rate scheduler. Called in
train()
, after callinginit_transform()
,init_model()
andinit_optimizer()
.- Parameters
dataset_train (
torch.utils.data.Dataset
) – The training (torch) dataset constructed intrain()
.
-
property
scheduler
¶ torch learning rate scheduler: The scheduler, usually set by
init_scheduler()
, which gets called intrain()
.
-
property
batch_size
¶
-
property
epochs
¶
-
property
lr
¶
-
property
normalize_by_opnorm
¶
-
save_learned_params
(path)[source]¶ Save learned parameters to file.
- Parameters
path (str) – Path at which the learned parameters should be saved. Implementations may interpret this as a file path or as a directory path for multiple files (which then should be created if it does not exist). If the implementation expects a file path, it should accept it without file ending.
-
load_learned_params
(path, convert_data_parallel='auto')[source]¶ Load learned parameters from file.
- Parameters
path (str) – Path at which the learned parameters are stored. Implementations may interpret this as a file path or as a directory path for multiple files. If the implementation expects a file path, it should accept it without file ending.
convert_data_parallel (bool or {
'auto'
,'keep'
}, optional) –Whether to automatically convert the model weight names if
model
is ann.DataParallel
-model but the stored state dict stems from a non-data-parallel model, or vice versa.'auto'
orTrue
:Auto-convert weight names, depending on the type of
model
.'keep'
orFalse
:Do not convert weight names. Convert to plain weight names.
-