CIL
CIL copied to clipboard
TomographicImaging
Improved documentation layout for algorithm class
Description
Closes #1793
Looks better
Help on class Algorithm in module cil.optimisation.algorithms.Algorithm:
class Algorithm(builtins.object)
| Algorithm(update_objective_interval=1, max_iteration=None, log_file=None)
|
| Base class for iterative algorithms that provides the minimal infrastructure.
|
| Algorithms are iterables so can be easily run in a for loop. They will stop as soon as the stop criterion is met.
| The user is required to implement the :code:`set_up`, :code:`__init__`, :code:`update` and :code:`update_objective` methods.
|
| The method :code:`run` is available to run :code:`n` iterations. The method accepts a :code:`callbacks` list of callables, each of which receive the current Algorithm object (
which in turn contains the iteration number and the actual objective value) and can be used to trigger print to screens and other user interactions. The :code:`run` method will st
op when the stopping criterion is met or `StopIteration` is raised.
|
| Parameters
| ----------
| update_objective_interval: int, optional, default 1
| the interval every which we would save the current objective. 1 means every iteration, 2 every 2 iteration and so forth. This is by default 1 and should be increased when
evaluating the objective is computationally expensive.
|
| Methods defined here:
|
| __init__(self, update_objective_interval=1, max_iteration=None, log_file=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| __iter__(self)
| Algorithm is an iterable
|
| __next__(self)
| Algorithm is an iterable
|
| This method triggers :code:`update()` and :code:`update_objective()`
|
| get_last_loss(self, return_all=False)
| Returns the last stored value of the loss function. If `update_objective_interval` is 1 it is the value of the objective at the current iteration. If update_objective_inte
rval > 1 it is the last stored value.
| Returns
| -------
| Float
| Last stored value of the loss function
|
| get_last_objective = get_last_loss(self, return_all=False)
|
| get_output(self)
| Returns the current solution.
|
| is_provably_convergent(self)
| Check if the algorithm is convergent based on the provable convergence criterion.
|
| Returns
| -------
| Boolean
| Outcome of the convergence check
|
| max_iteration_stop_criterion(self)
| Do not use: this is being deprecated
|
| objective_to_dict(self, verbose=False)
| Internal function to save and print objective functions
|
| objective_to_string(self, verbose=False)
| Do not use: this is being deprecated
|
| run(self, iterations=None, callbacks: Optional[List[cil.optimisation.utilities.callbacks.Callback]] = None, verbose=1, **kwargs)
| run upto :code:`iterations` with callbacks/logging.
|
| For a demonstration of callbacks see https://github.com/TomographicImaging/CIL-Demos/blob/main/misc/callback_demonstration.ipynb
|
| Parameters
| -----------
| iterations: int, default is None
| Number of iterations to run. If not set the algorithm will run until :code:`should_stop()` is reached
| callbacks: list of callables, default is Defaults to :code:`[ProgressCallback(verbose)]`
| List of callables which are passed the current Algorithm object each iteration. Defaults to :code:`[ProgressCallback(verbose)]`.
| verbose: 0=quiet, 1=info, 2=debug
| Passed to the default callback to determine the verbosity of the printed output.
|
| set_up(self, *args, **kwargs)
| Set up the algorithm
|
| should_stop(self)
| default stopping criterion: number of iterations
|
| The user can change this in concrete implementation of iterative algorithms.
|
| update(self)
| A single iteration of the algorithm
|
| update_objective(self)
| calculates the objective with the current solution
|
| verbose_header(self, *_, **__)
| Do not use: this is being deprecated
|
| verbose_output(self, *_, **__)
| Do not use: this is being deprecated
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| iterations
| returns the iterations at which the objective has been evaluated
|
| loss
| returns the list of the values of the objective during the iteration
| The length of this list may be shorter than the number of iterations run when the update_objective_interval > 1
|
| objective
| returns the list of the values of the objective during the iteration
|
| The length of this list may be shorter than the number of iterations run when the update_objective_interval > 1
|
| solution
| Returns the current solution.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| max_iteration
| gets the maximum number of iterations
|
| update_objective_interval
| gets the update_objective_interval
Checklist
- [x] I have performed a self-review of my code
- [x] I have added docstrings in line with the guidance in the developer guide
- [x] I have updated the relevant documentation ~- [ ] I have implemented unit tests that cover any new or modified functionality~
- [ ] CHANGELOG.md has been updated with any functionality change
- [x] Request review from all relevant developers
- [x] Change pull request label to 'Waiting for review'
Contribution Notes
Please read and adhere to the developer guide and local patterns and conventions.
- [x] The content of this Pull Request (the Contribution) is intentionally submitted for inclusion in CIL (the Work) under the terms and conditions of the Apache-2.0 License
- [x] I confirm that the contribution does not violate any intellectual property rights of third parties
