Creating your own backend#
By creating your own backend you can extend functionality and edit the existing server workflow. If you are using clingo, we highly recomend extending the ClingoMultishotBackend to create your own. This backend contains multiple functionalities already built in wich can be overwritten and extended. The following explanation assumes that this is the backend that is being extended.
Note
If you will not use multi-shot functionalities, assumptions and exterals you can also extend the ClingoBackend.
Note
Using your backend
To make your custom backend avaliable to clinguin, you must provide the path via the command line argument --custom-classes
.
In what follows we divide the possible extensions. For more implementation details, look at the source code All the presented methods can be overwritten to your desire.
Constructor#
In the constructor one can add custom arguments and new domain-state constructors.
- ClingoMultishotBackend.__init__(args)[source]#
Creates the Backend with the given arguments. It will setup the context, files and constants. It will define all domain-state constructors and their cache. Finally, it calls all the setup methods: (_init_setup, _outdate,_init_ctl) and grounds the control
- Parameters
args (ArgumentParser) – The arguments from the argument parser that are given for the registered options.
Register options#
By overwritting this class method, one can add new arguments to the command line. These options will be added under a group for the created backend.
Examples
- classmethod ClingoMultishotBackend.register_options(parser)#
Registers options in the command line for the domain files and ui files.
- Parameters
parser (ArgumentParser) – A group of the argparse argument parser
Setups#
These methods will handle the arguments depending on the clinguin state. Some are called at the start after a restart or when a change is done in the solving. When a custom argument is added to the backend if will likely need to be handled here.
Examples
- ClingoMultishotBackend._init_setup()[source]#
Initializes the arguments when the server starts or after a restart. These arguments include, the handler and iterator for browsing answer sets, as well as the domain control, the atoms, assumptions and externals
- ClingoMultishotBackend._init_ctl()#
Initializes the control object (domain-control). It is used when the server is started or after a restart. Uses the provided constants and domain files. It adds the atoms.
- ClingoMultishotBackend._outdate()#
Outdates all the dynamic values when a change has been made. Any current interaction in the models wil be terminated by canceling the search and removing the iterator.
- ClingoMultishotBackend._is_browsing()#
Property to tell if clinguin is in browsing mode.
Solving#
These methods are involved on how the domain control is solved. They can be ovweritten for theory extensions among other things.
Examples
- ClingoMultishotBackend._ground(program='base')#
Grounds the provided program
- Parameters
program (str) – The name of the program to ground (defaults to “base”)
- ClingoMultishotBackend._prepare()#
Does any preparation before a solve call.
- ClingoMultishotBackend._on_model(model)#
This method is called each time a model is obtained by the domain control. It can be used to extend the given model in Theory Solving.
- Parameters
model (clingo.Model) – The found clingo model
- ClingoMultishotBackend._add_atom(predicate_symbol)#
Adds an atom if it hasn’t been already aded
- Parameters
predicate_symbol (clingo.Symbool) – The symbol for the atom
UI updates#
If any changes want to be made in how the UI state is computed they can be made by overwritting this method.
Examples
- ClingoMultishotBackend._update_ui_state()#
Updates the UI state by calling all domain state methods and creating a new control object (ui_control) using the ui_files provided
Domain state#
These methods take care of generating the domain-state. When new information wants to be added a domain state constructor can be included. These domain constructors will be automatically called by the _domain_state property. But, they need to be previously registered in the constructor using the functions below.
Note
Some of the domain constructors involve extra work so they are handled as @cache_property
.
Warning
Make sure any domain constructor added is a property with anotation @property
- ClingoMultishotBackend._add_domain_state_constructor(method: str)#
Adds a method name to the domain constructors. This method needs to be annotated with
@property
or@cached_property
- Parameters
method (str) – Name of the property method
- ClingoMultishotBackend._clear_cache(methods=None)#
Clears the cache of domain state constructor methods
- Parameters
methods (list, optional) – A list with the methods to remove the cache from. If no value is passed then all cache is removed
Note
Domain state constructors for this backend are showed in the section above. These constructors can also be overwritten if necessary.
Output#
The propery method below is used to generate an output program for downloads
- ClingoMultishotBackend._output_prg()#
Generates the output program used when downloading into a file. Includes all assumptions as facts.
Public operations#
Each backend can define any number public operations or overwrite the existing ones. These operations are any public method of the class and will be accessible to the UI.
Examples