diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 0f9b4d73..85b2076b 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -10,4 +10,25 @@ background-color: hsl(257, 20%, 50%); div.admonition.example > .admonition-title::before { content: "\f2a7"; - } \ No newline at end of file + } + +.sidebar-logo { + margin: inherit; +} +.sidebar-logo-container{ + max-width: 20%!important; + margin-top: 0.2rem; + margin-right: 0.2rem; + justify-content: flex-end; + display: flex; +} +.sidebar-brand-text { + text-align: center !important; + /* color: #004C6E !important; */ + align-items: center; + display: inline-flex; +} + +.sidebar-brand { + flex-direction: row !important; +} \ No newline at end of file diff --git a/docs/_static/logo-dark-mode.png b/docs/_static/logo-dark-mode.png new file mode 100644 index 00000000..81ed997a Binary files /dev/null and b/docs/_static/logo-dark-mode.png differ diff --git a/docs/_static/logo-light-mode.png b/docs/_static/logo-light-mode.png new file mode 100644 index 00000000..d2ac73df Binary files /dev/null and b/docs/_static/logo-light-mode.png differ diff --git a/docs/clinguin/backends.rst b/docs/clinguin/backends.rst deleted file mode 100644 index 34ed131e..00000000 --- a/docs/clinguin/backends.rst +++ /dev/null @@ -1,413 +0,0 @@ - -Backends -######## - -The backends listed here are provided with clinguin. -All available functions that can be referenced in the :ref:`ui-state` for each backend are listed below. -Notice that all backends will also include the functionalities of the ones they extend. - -The source code for the backends can be found in `github `_. - -.. currentmodule:: clinguin.server.application.backends - -ClingoBackend ---------------- - - Implements all basic clingo functionality for single-shot solving. - - .. admonition:: Examples - :class: example - - * `sudoku_single_shot `_ - - - - .. autoclass:: ClingoBackend - :members: - :noindex: - :exclude-members: register_options, get - - **Domain state constructors** - - The domain state also inclues domain constructors from the parent class. - - .. automethod:: ClingoBackend._ds_context - - .. automethod:: ClingoBackend._ds_brave - - .. automethod:: ClingoBackend._ds_cautious - - .. automethod:: ClingoBackend._ds_model - - .. automethod:: ClingoBackend._ds_unsat - - .. automethod:: ClingoBackend._ds_browsing - - -ClingoMultishotBackend ----------------------- - - Extends :ref:`ClingoBackend` with functionality for multi-shot solving. Adds options to access and store assumptions and externals. - - .. admonition:: Examples - :class: example - - * `sudoku `_ - * `jobshop `_ - * `placement `_ - - - .. autoclass:: ClingoMultishotBackend - :members: - :noindex: - :exclude-members: register_options - - **Domain state constructors** - - The domain state also inclues domain constructors from the parent class. - - .. automethod:: ClingoMultishotBackend._ds_assume - -ClingraphBackend ----------------- - - Extends :ref:`ClingoMultishotBackend` with functionality to render and interact with `clingraph `_ images. - - .. warning:: - - To use this backend you might need to manually install Graphviz. See the `clingraph instalaltion `_ for details. - - .. admonition:: Examples - :class: example - - * `graph_coloring `_ - * `tree_browser `_ - * `ast `_ - - - This backend will allow the use of clingraph images inside a canvas element. - To use this feature, the user must provide a clingraph visualization encoding via the command line in argument ``--clingraph-files``. - The input to this encoding will be the :ref:`domain-state` (same input as for the :ref:`ui-files`). - - .. tip:: - - The clingraph encoding will also have information about brave, and cautious consequences. - So dont be afraid to use it in the graphs! - - A clinguin ``canvas`` is enhanced with an attribute ``image_type``. - When the value for this attirbute starts with ``clingraph`` it will be substituted by the :ref:`ClingraphBackend` for the ``svg`` representation of the graph. - By default the graph named ``default`` will be used, another graph with name ``X`` can be used by setting the image type to ``clingraph__X`` - - .. note:: - - To use this backend with the :ref:`TkinterFrontend`, you must provide the option ``--intermediate-format=png``. - - .. admonition:: Examples - :class: example - - Creates a canvas in a window that will contain the default clingraph graph - - .. code-block:: - - elem(c, canvas, window). - attr(c, image_type, clingraph). - - - **Interacting with the graph** - - To interact with the clingraph nodes/edges, additional steps must be made. - Each node/edge must be added to the UI as an element inside the canvas using the type ``svg_node`` (``svg_edge``). - This type of elements require the identifier of the clingraph node/edge in argument ``clingraph_id`` - to link the interactivity with the svg element generated by clingraph. - - .. admonition:: Examples - :class: example - - Continuation of the previous example. - - .. code-block:: - - elem(n(X), svg_node, c). - attr(n(X), clingraph_id, X):- node(X). - - ``node(X)`` is generated in the `ui-files` - - - .. tip:: - - Notice that the clingraph nodes are not accesible by the `ui-files`. - Therefore, nodes of the clingraph images have to be generated again in this encoding. - - Consider separating the clingraph node generation into a diferent encoding, - and then including it in the UI and clingraph encodings. - - .. warning:: - - The interactive feature only work in web based frontends, not in Tkinter. - - .. note:: - - ``update`` actions applied to clingraph elements (`svg_nodes`) will update the html style, not the graphviz properties. - Therefore, it can be used to set things like visibility and opacity but not internal clingraph values. - - - .. autoclass:: ClingraphBackend - :members: - :noindex: - :exclude-members: register_options - - - -ExplanationBackend ------------------- - - Extends :ref:`ClingoMultishotBackend` with functionality to compute Minumal Unsatisfiable Cores (MUC) when there is an UNSAT output. - - .. admonition:: Examples - :class: example - - * `sudoku_advanced `_ - * `sudoku_explained `_ - - - When the :ref:`domain-control` produces an unsatisfiable output this backend will perform subsequents calls - to find the subset minimal assumptions that caused the unsatisfiablity. - These assuptions not only include those selected by the user, but also can be part of the input. - This is needed when some of the input facts also want to be shown to the user. - Therefore, this backend adds an argument to the command line: ``--assumption-signature`` - in which the user can select which signatures will be considered as assumptions in the MUC computation. - - .. admonition:: Examples - :class: example - - The `sudoku_advanced `_ example - provides the argument ``--assumption-signature=initial,3`` so that all the initial values of the sudoku - are also considered in the unsat core and therefore shown to the user. - - .. code-block:: - - attr(pos(X,Y),class,"bg-primary"):-pos(X,Y), not _clinguin_muc(sudoku(X,Y,_)), not _clinguin_muc(initial(X,Y,_)). - attr(pos(X,Y),class,"bg-danger"):-pos(X,Y), _clinguin_muc(sudoku(X,Y,_)). - attr(pos(X,Y),class,"bg-danger"):-pos(X,Y), _clinguin_muc(initial(X,Y,_)). - - The :ref:`domain-state` is then enhanced by the MUC using predicate ``muc/1``. - - .. admonition:: Examples - :class: example - - In the sudoku, the MUC information will show in red the faulty assumptions. - - .. code-block:: - - attr(pos(X,Y),class,"bg-primary"):-pos(X,Y), not _clinguin_muc(sudoku(X,Y,_)), not _clinguin_muc(initial(X,Y,_)). - attr(pos(X,Y),class,"bg-danger"):-pos(X,Y), _clinguin_muc(sudoku(X,Y,_)). - attr(pos(X,Y),class,"bg-danger"):-pos(X,Y), _clinguin_muc(initial(X,Y,_)). - - - .. autoclass:: ExplanationBackend - :members: - :noindex: - :exclude-members: register_options - - - **Domain state constructors** - - The domain state also inclues domain constructors from the parent class. - - .. automethod:: ExplanationBackend._ds_muc - -ClingoDLBackend ---------------- - - Extends :ref:`ClingoMultishotBackend` with functionality to accept clingo-dl programs as input. - - .. admonition:: Examples - :class: example - - * `jobshop `_ - - - The :ref:`domain-state` is then enhanced by predicate ``_clinguin_assign/2``. - - - .. admonition:: Examples - :class: example - - In the jobshop example, the assignment is used for the label of the job. - - .. code-block:: - - elem(tctime(T,ST), label, tc(T,ST)):- _clinguin_assign((T,ST),Start). - attr(tctime(T,ST), label, @concat("","@",Start,"-",Start+ET)):- _clinguin_assign((T,ST),Start), executionTime(T,ST,ET). - attr(tctime(T,ST), class, "fw-light"):- _clinguin_assign((T,ST),Start). - attr(tctime(T,ST), fontSize, "8px"):- _clinguin_assign((T,ST),Start). - - .. warning:: - - Notice that asisgnments are not part of the brave or cautious consequences - - - .. autoclass:: ClingoDLBackend - :members: - :noindex: - :exclude-members: register_options - - - **Domain state constructors** - - The domain state also inclues domain constructors from the parent class. - - .. automethod:: ClingoDLBackend._ds_assign - -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 :ref:`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 :ref:`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. - - .. admonition:: Examples - :class: example - - * `explanation_backend `_ - * `clingraph_backend `_ - * `clingodl_backend `_ - - .. automethod:: ClingoMultishotBackend.__init__ - - - **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. - - .. admonition:: Examples - :class: example - - * `explanation_backend `_ - * `clingraph_backend `_ - - .. automethod:: ClingoMultishotBackend.register_options - - **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. - - .. admonition:: Examples - :class: example - - * `explanation_backend `_ - * `clingodl_backend `_ - - - .. automethod:: ClingoMultishotBackend._init_setup - - .. automethod:: ClingoMultishotBackend._init_ctl - - .. automethod:: ClingoMultishotBackend._outdate - - .. automethod:: ClingoMultishotBackend._is_browsing - - - **Solving** - - These methods are involved on how the domain control is solved. - They can be ovweritten for theory extensions among other things. - - .. admonition:: Examples - :class: example - - * `explanation_backend `_ - * `clingodl_backend `_ - - .. automethod:: ClingoMultishotBackend._ground - - .. automethod:: ClingoMultishotBackend._prepare - - .. automethod:: ClingoMultishotBackend._on_model - - .. automethod:: ClingoMultishotBackend._add_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. - - .. admonition:: Examples - :class: example - - * `clingraph_backend `_ - - - .. automethod:: ClingoMultishotBackend._update_ui_state - - - **Domain state** - - These methods take care of generating the :ref:`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. - - .. admonition:: Examples - :class: example - - * `explanation_backend `_ - * `clingodl_backend `_ - * `clingraph_backend `_ - - .. 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`` - - .. automethod:: ClingoMultishotBackend._add_domain_state_constructor - - .. automethod:: ClingoMultishotBackend._clear_cache - - .. 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 - - .. automethod:: ClingoMultishotBackend._output_prg - - - **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. - - .. admonition:: Examples - :class: example - - * `explanation_backend `_ diff --git a/docs/clinguin/backends/ClingoBackend.rst b/docs/clinguin/backends/ClingoBackend.rst new file mode 100644 index 00000000..5cf9061e --- /dev/null +++ b/docs/clinguin/backends/ClingoBackend.rst @@ -0,0 +1,34 @@ +ClingoBackend +--------------- + +Implements all basic clingo functionality for single-shot solving. + +.. admonition:: Examples + :class: example + + * `sudoku_single_shot `_ + +.. currentmodule:: clinguin.server.application.backends + + +.. autoclass:: ClingoBackend + :members: + :noindex: + :exclude-members: register_options, get + +Domain state constructors ++++++++++++++++++++++++++ + +The domain state also inclues domain constructors from the parent class. + +.. automethod:: ClingoBackend._ds_context + +.. automethod:: ClingoBackend._ds_brave + +.. automethod:: ClingoBackend._ds_cautious + +.. automethod:: ClingoBackend._ds_model + +.. automethod:: ClingoBackend._ds_unsat + +.. automethod:: ClingoBackend._ds_browsing \ No newline at end of file diff --git a/docs/clinguin/backends/ClingoDLBackend.rst b/docs/clinguin/backends/ClingoDLBackend.rst new file mode 100644 index 00000000..eefc641a --- /dev/null +++ b/docs/clinguin/backends/ClingoDLBackend.rst @@ -0,0 +1,43 @@ +ClingoDLBackend +--------------- + +Extends :ref:`ClingoMultishotBackend` with functionality to accept clingo-dl programs as input. + +.. admonition:: Examples + + + * `jobshop `_ + + +The :ref:`domain-state` is then enhanced by predicate ``_clinguin_assign/2``. + + +.. admonition:: Examples + + + In the jobshop example, the assignment is used for the label of the job. + + .. code-block:: + + elem(tctime(T,ST), label, tc(T,ST)):- _clinguin_assign((T,ST),Start). + attr(tctime(T,ST), label, @concat("","@",Start,"-",Start+ET)):- _clinguin_assign((T,ST),Start), executionTime(T,ST,ET). + attr(tctime(T,ST), class, "fw-light"):- _clinguin_assign((T,ST),Start). + attr(tctime(T,ST), fontSize, "8px"):- _clinguin_assign((T,ST),Start). + +.. warning:: + + Notice that asisgnments are not part of the brave or cautious consequences + +.. currentmodule:: clinguin.server.application.backends + +.. autoclass:: ClingoDLBackend + :members: + :noindex: + :exclude-members: register_options + + +**Domain state constructors** + +The domain state also inclues domain constructors from the parent class. + +.. automethod:: ClingoDLBackend._ds_assign diff --git a/docs/clinguin/backends/ClingoMultishotBackend.rst b/docs/clinguin/backends/ClingoMultishotBackend.rst new file mode 100644 index 00000000..2079b6cc --- /dev/null +++ b/docs/clinguin/backends/ClingoMultishotBackend.rst @@ -0,0 +1,25 @@ + +ClingoMultishotBackend +---------------------- + +Extends :ref:`ClingoBackend` with functionality for multi-shot solving. Adds options to access and store assumptions and externals. + +.. admonition:: Examples + + + * `sudoku `_ + * `jobshop `_ + * `placement `_ + +.. currentmodule:: clinguin.server.application.backends + +.. autoclass:: ClingoMultishotBackend + :members: + :noindex: + :exclude-members: register_options + +**Domain state constructors** + +The domain state also inclues domain constructors from the parent class. + +.. automethod:: ClingoMultishotBackend._ds_assume \ No newline at end of file diff --git a/docs/clinguin/backends/ClingraphBackend.rst b/docs/clinguin/backends/ClingraphBackend.rst new file mode 100644 index 00000000..6403510c --- /dev/null +++ b/docs/clinguin/backends/ClingraphBackend.rst @@ -0,0 +1,93 @@ + +ClingraphBackend +---------------- + +Extends :ref:`ClingoMultishotBackend` with functionality to render and interact with `clingraph `_ images. + +.. warning:: + + To use this backend you might need to manually install Graphviz. See the `clingraph instalaltion `_ for details. + +.. admonition:: Examples + + + * `graph_coloring `_ + * `tree_browser `_ + * `ast `_ + + +This backend will allow the use of clingraph images inside a canvas element. +To use this feature, the user must provide a clingraph visualization encoding via the command line in argument ``--clingraph-files``. +The input to this encoding will be the :ref:`domain-state` (same input as for the :ref:`ui-files`). + +.. tip:: + + The clingraph encoding will also have information about brave, and cautious consequences. + So dont be afraid to use it in the graphs! + +A clinguin ``canvas`` is enhanced with an attribute ``image_type``. +When the value for this attirbute starts with ``clingraph`` it will be substituted by the :ref:`ClingraphBackend` for the ``svg`` representation of the graph. +By default the graph named ``default`` will be used, another graph with name ``X`` can be used by setting the image type to ``clingraph__X`` + +.. note:: + + To use this backend with the :ref:`TkinterFrontend`, you must provide the option ``--intermediate-format=png``. + +.. admonition:: Examples + + + Creates a canvas in a window that will contain the default clingraph graph + + .. code-block:: + + elem(c, canvas, window). + attr(c, image_type, clingraph). + +.. currentmodule:: clinguin.server.application.backends + + +Interacting with the graph +++++++++++++++++++++++++++ + + +To interact with the clingraph nodes/edges, additional steps must be made. +Each node/edge must be added to the UI as an element inside the canvas using the type ``svg_node`` (``svg_edge``). +This type of elements require the identifier of the clingraph node/edge in argument ``clingraph_id`` +to link the interactivity with the svg element generated by clingraph. + +.. admonition:: Examples + + + Continuation of the previous example. + + .. code-block:: + + elem(n(X), svg_node, c). + attr(n(X), clingraph_id, X):- node(X). + + ``node(X)`` is generated in the `ui-files` + + +.. tip:: + + Notice that the clingraph nodes are not accesible by the `ui-files`. + Therefore, nodes of the clingraph images have to be generated again in this encoding. + + Consider separating the clingraph node generation into a diferent encoding, + and then including it in the UI and clingraph encodings. + +.. warning:: + + The interactive feature only work in web based frontends, not in Tkinter. + +.. note:: + + ``update`` actions applied to clingraph elements (`svg_nodes`) will update the html style, not the graphviz properties. + Therefore, it can be used to set things like visibility and opacity but not internal clingraph values. + + +.. autoclass:: ClingraphBackend + :members: + :noindex: + :exclude-members: register_options + diff --git a/docs/clinguin/backends/Custom.rst b/docs/clinguin/backends/Custom.rst new file mode 100644 index 00000000..9bb8707f --- /dev/null +++ b/docs/clinguin/backends/Custom.rst @@ -0,0 +1,162 @@ +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 :ref:`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 :ref:`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. + +.. admonition:: Examples + + + * `explanation_backend `_ + * `clingraph_backend `_ + * `clingodl_backend `_ + +.. currentmodule:: clinguin.server.application.backends + +.. automethod:: ClingoMultishotBackend.__init__ + + +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. + +.. admonition:: Examples + + + * `explanation_backend `_ + * `clingraph_backend `_ + +.. automethod:: ClingoMultishotBackend.register_options + +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. + +.. admonition:: Examples + + + * `explanation_backend `_ + * `clingodl_backend `_ + + +.. automethod:: ClingoMultishotBackend._init_setup + +.. automethod:: ClingoMultishotBackend._init_ctl + +.. automethod:: ClingoMultishotBackend._outdate + +.. automethod:: ClingoMultishotBackend._is_browsing + + +Solving ++++++++ + +These methods are involved on how the domain control is solved. +They can be ovweritten for theory extensions among other things. + +.. admonition:: Examples + + + * `explanation_backend `_ + * `clingodl_backend `_ + +.. automethod:: ClingoMultishotBackend._ground + +.. automethod:: ClingoMultishotBackend._prepare + +.. automethod:: ClingoMultishotBackend._on_model + +.. automethod:: ClingoMultishotBackend._add_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. + +.. admonition:: Examples + + + * `clingraph_backend `_ + + +.. automethod:: ClingoMultishotBackend._update_ui_state + + +Domain state +++++++++++++ + +These methods take care of generating the :ref:`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. + +.. admonition:: Examples + + + * `explanation_backend `_ + * `clingodl_backend `_ + * `clingraph_backend `_ + +.. 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`` + +.. automethod:: ClingoMultishotBackend._add_domain_state_constructor + +.. automethod:: ClingoMultishotBackend._clear_cache + +.. 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 + +.. automethod:: ClingoMultishotBackend._output_prg + + +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. + +.. admonition:: Examples + + + * `explanation_backend `_ diff --git a/docs/clinguin/backends/ExplanationBackend.rst b/docs/clinguin/backends/ExplanationBackend.rst new file mode 100644 index 00000000..8e039b7b --- /dev/null +++ b/docs/clinguin/backends/ExplanationBackend.rst @@ -0,0 +1,60 @@ +ExplanationBackend +------------------ + +Extends :ref:`ClingoMultishotBackend` with functionality to compute Minumal Unsatisfiable Cores (MUC) when there is an UNSAT output. + +.. admonition:: Examples + + + * `sudoku_advanced `_ + * `sudoku_explained `_ + + +When the :ref:`domain-control` produces an unsatisfiable output this backend will perform subsequents calls +to find the subset minimal assumptions that caused the unsatisfiablity. +These assuptions not only include those selected by the user, but also can be part of the input. +This is needed when some of the input facts also want to be shown to the user. +Therefore, this backend adds an argument to the command line: ``--assumption-signature`` +in which the user can select which signatures will be considered as assumptions in the MUC computation. + +.. currentmodule:: clinguin.server.application.backends + + +.. admonition:: Examples + + + The `sudoku_advanced `_ example + provides the argument ``--assumption-signature=initial,3`` so that all the initial values of the sudoku + are also considered in the unsat core and therefore shown to the user. + + .. code-block:: + + attr(pos(X,Y),class,"bg-primary"):-pos(X,Y), not _clinguin_muc(sudoku(X,Y,_)), not _clinguin_muc(initial(X,Y,_)). + attr(pos(X,Y),class,"bg-danger"):-pos(X,Y), _clinguin_muc(sudoku(X,Y,_)). + attr(pos(X,Y),class,"bg-danger"):-pos(X,Y), _clinguin_muc(initial(X,Y,_)). + +The :ref:`domain-state` is then enhanced by the MUC using predicate ``muc/1``. + +.. admonition:: Examples + + + In the sudoku, the MUC information will show in red the faulty assumptions. + + .. code-block:: + + attr(pos(X,Y),class,"bg-primary"):-pos(X,Y), not _clinguin_muc(sudoku(X,Y,_)), not _clinguin_muc(initial(X,Y,_)). + attr(pos(X,Y),class,"bg-danger"):-pos(X,Y), _clinguin_muc(sudoku(X,Y,_)). + attr(pos(X,Y),class,"bg-danger"):-pos(X,Y), _clinguin_muc(initial(X,Y,_)). + + +.. autoclass:: ExplanationBackend + :members: + :noindex: + :exclude-members: register_options + + +Domain state constructors + +The domain state also inclues domain constructors from the parent class. + +.. automethod:: ExplanationBackend._ds_muc \ No newline at end of file diff --git a/docs/clinguin/backends/index.rst b/docs/clinguin/backends/index.rst new file mode 100644 index 00000000..5bee4c4c --- /dev/null +++ b/docs/clinguin/backends/index.rst @@ -0,0 +1,32 @@ + +Backends +######## + +The backends listed here are provided with clinguin. +All available functions that can be referenced in the :ref:`ui-state` for each backend are listed below. +Notice that all backends will also include the functionalities of the ones they extend. + +The source code for the backends can be found in `github `_. + +.. currentmodule:: clinguin.server.application.backends + + +Built-in Backends ++++++++++++++++++ + +.. toctree:: + :maxdepth: 1 + + ClingoBackend.rst + ClingoMultishotBackend.rst + ClingraphBackend.rst + ExplanationBackend.rst + ClingoDLBackend.rst + +Customization ++++++++++++++ + +.. toctree:: + :maxdepth: 1 + + Custom.rst \ No newline at end of file diff --git a/docs/clinguin/development.rst b/docs/clinguin/development.rst index 69681cd7..540dbafd 100644 --- a/docs/clinguin/development.rst +++ b/docs/clinguin/development.rst @@ -1,5 +1,5 @@ -Development -=========== +Contributing +============ Angular Frontend Development ++++++++++++++++++++++++++++ @@ -15,9 +15,9 @@ For instance to create new element types. Requirements ------------ - - `NPM `_ - - `NODE `_ - - `Angular `_ +- `NPM `_ +- `NODE `_ +- `Angular `_ Usage ----- diff --git a/docs/clinguin/frontends.rst b/docs/clinguin/frontends.rst deleted file mode 100644 index b8366083..00000000 --- a/docs/clinguin/frontends.rst +++ /dev/null @@ -1,558 +0,0 @@ -Frontends -######### - -The frontends listed here are provided with clinguin. Each frontend allows different element types, arguments, and events. - -The source code for the frontends can be found on `GitHub `_. - - -TkinterFrontend ---------------- - -This frontend uses the standard Python interface `tkinter `_ to generate a UI. - -.. admonition:: Examples - :class: example - - * `Tkinter Examples `_ - -One can look up the available elements, with the corresponding attributes and callback actions using: - -.. code-block:: bash - - $ clinguin client-server --frontend-syntax - -If one is also interested in what values one might set, one can also look at the full syntax: - -.. code-block:: bash - - $ clinguin client-server --frontend-syntax-full - -AngularFrontend ---------------- - -This frontend was developed using `Angular `_. -For styling, it uses the `bootstrap `_ library with `Angular-Boostrap `_. -Thus, providing beautiful components out of the box by giving access to Bootstrap classes for styling. -For contributing with new components take a look at the :ref:`Development` section. - -.. admonition:: Examples - :class: example - - * `Angular Examples `_ - -.. tip:: - - It implements most of the elements and attributes of the TkinterFrontend. - So you can also check the Tkinter Syntax as explaned above and try setting those values. - -Atributes -+++++++++ - -.. note:: - - Any attribute that is passed that does not fall under this list or the specific attributes of the element, - will be set as a plain html style in the component - - -Class -..... - - The class atribute ``class`` will add a `bootstrap class `_ - to any element. - This attribute can apear multiple times. - - .. tip:: - - **Simplify, use classes!** - - It is encouranged to use classes for styling with the predefined colors. - Must of the attributes found below can be replaced by a bootstrap class. - - Not only that but you can set multiple classes in the same ASP rule using - - ``attr(ID,class,(C1;C2;...))`` - - - -Positioning -............ - - .. _Child layout: - - **Child layout** - - ``child_layout`` - - *Description*: With this attribute one can define the layout of the children, i.e. how they are positioned. - - *Values*: For the child-layout four different options exists: - - - ``flex`` (default, tries to do it automatically) - - ``grid`` (grid-like-specification) - - ``absstatic`` (if one wants to specify the position with absolute-pixelcoordinates) - - ``relstatic`` (if one wants to specify the position with relative-pixel coordinates(from 0 to 100 percent, where 0 means left/top and 100 means right/bottom)). - - They can either bespecified via a clingo symbol or via a string (string is case-insensitive). - - - .. _Grid: - - **Grid** - - ``grid_column`` - - *Description*: With this attribute one can define in which column the element shall be positioned. - - *Values*: Integer - - ``grid_row`` - - *Description*: With this attribute one can define in which row the element shall be positioned. - - *Values*: Integer - - ``grid_column_span`` - - *Description*: With this attribute one can define, that the elements stretches over several columns. - - *Values*: Integer - - ``grid_row_span`` - - *Description*: With this attribute one can define, that the elements stretches over several rows. - - *Values*: Integer - - - - .. _Relative and Absolute: - - **Relative and Absolute** - - ``pos_x`` - - *Description*: With this attribute one sets the x-position of the element - it depends on the parents ``child-layout`` how this is defined (either pixels, relative as a percentage, ...). - - *Values*: Integer - - ``pos_y`` - - *Description*: With this attribute one sets the y-position of the element - it depends on the parents ``child-layout`` how this is defined (either pixels, relative as a percentage, ...). - - *Values*: Integer - - - .. _Direction: - - **Direction** - - .. tip :: - - Try using `boostrap positioning `_ instead. - - - ``flex_direction`` - - *Description*: With this attribute one can set the ``direction`` (i.e., where it gets placed) of anelement which root has a specified flex layout. - - *Values*: For the flex-direction type two possible values exist: - - - ``column`` (vertical alignment) - - ``row`` (horizontal alignment). - -Style -..... - - .. _Color: - - **Color** - - .. tip :: - - Try using `boostrap colors `_ instead. - - - ``background_color`` - - *Description*: With this attribute one can define the background-color of the element. - - *Values*: Color - - ``foreground_color`` - - *Description*: With this attribute one can set the foreground-color of the element. - - *Values*: Color - - ``border_color`` - - *Description*: With this attribute one may set the border color. - - *Values*: Color - - ``on_hover`` - - *Description*: With this attribute one can enable or disable on-hover features for the element. - - *Values*: For the boolean type, either true or false are allowed - either as string or as a clingo-symbol. If one provides it as a string, it is case-insensitive. - - ``on_hover_background_color`` - - *Description*: With this attribute one can set the background color the element shall have, when on_hover is enabled. - - *Values*: Color - - ``on_hover_foreground_color`` - - *Description*: With this attribute one can set the forground color the element shall have, when on_hover is eneabled. - - *Values*: Color - - ``on_hover_border_color`` - - *Description*: With this attribute one can set the color the border of the element shall have, when on_hover is enabled. - - *Values*: Color - - - .. _Size: - - **Size** - - ``height`` - - *Description*: With this attribute one can set the height in pixels of the element. - - *Values*: Integer - - ``width`` - - *Description*: With this attribute one can set the width in pixels of the element. - - *Values*: Integer - - - .. _Border: - - **Border** - - .. tip :: - - Try using `boostrap borders `_ instead. - - ``border_width`` - - *Description*: With this attribute one defines the width of the border in pixels. - - *Values*: Integer - - ``border_color`` - - *Description*: With this attribute one may set the border color. - - *Values*: Color - - .. _Visibility: - - **Visibility** - - ``visibility`` - - *Description*: Sets the visibility of an element. It can be used to show things like a modal or a container using the update functionality - - *Values*: The visibility, options are: - - - ``visible``: To show the element - - ``hidden``: To hide the element - - .. _Text: - - **Text** - - .. tip :: - - Try using `boostrap text `_ style instead. - - -Elements -++++++++ - - -``window`` -.......... - - The main window of the UI. It is necesary to especify exacly one element of this type. - -``menu-bar`` -............ - - The menu bar that apear on top. - Notice that any button which is a children of this element will be placed as part of the menu. - - **Attributes** - - ``icon`` - - *Description*: The main icon of the application - - *Values*: `Font awesome `_ symbol name - - ``title`` - - *Description*: The title shown in the uper lext corner - - *Values*: String - - -``message`` -............ - - A message shown to the user in the bottom. Corresponds to a `boostrap alert `_. - It must always be contained in the window element. - - This element is also used internally to send messages from the server to the UI. - - **Attributes** - - :ref:`Visibility ` - - - ``type`` - - *Description* : With this attribute one can set the look - - *Values*: For the popup-types three different options exists: 'info' (Default information message),'warning' and 'error' - - ``title`` - - *Description* : With this attribute one can set the title of the alert. - - *Values*: String, can either be specified as a string or if it is simple as a symbol. - - ``message`` - - *Description* : With this attribute one can set the message of the alert. - - *Values*: String, can either be specified as a string or if it is simple as a symbol. - - -``context-menu`` -................ - - - A context menu that will open in the position of the click. - It must always be contained in the window element. - All buttons inside this element will apear as options. - - - **Attributes** - - :ref:`Visibility ` - -``modal`` -......... - - - A modal pop-up window. - Implemented using `boostrap modals `_. - It must always be contained in the window element. - - **Attributes** - - :ref:`Class `, - :ref:`Visibility ` - - ``title`` - - *Description* : The title of the modal - - *Values*: String - -``container`` -............. - - A container for defining layout. - Implemented using `boostrap modals `_. - - **Attributes** - - :ref:`Class `, - :ref:`Visibility `, - :ref:`Child layout `, - :ref:`Grid `, - :ref:`Relative and Absolute `, - :ref:`Direction `, - :ref:`Color `, - :ref:`Size `, - :ref:`Border `, - :ref:`Text ` - - ``title`` - - *Description* : The title of the modal - - *Values*: String - -``button`` -.......... - - A button. - Implemented using `boostrap buttons `_. - - **Attributes** - - :ref:`Class `, - :ref:`Visibility `, - :ref:`Grid `, - :ref:`Relative and Absolute `, - :ref:`Direction `, - :ref:`Color `, - :ref:`Size `, - :ref:`Border `, - :ref:`Text ` - - ``label`` - - *Description* : The text inside the button - - *Values*: String - - ``icon`` - - *Description*: The icon of the button - - *Values*: `Font awesome `_ symbol name - -``label`` -......... - - A label. - - **Attributes** - - :ref:`Class `, - :ref:`Visibility `, - :ref:`Grid `, - :ref:`Relative and Absolute `, - :ref:`Direction `, - :ref:`Color `, - :ref:`Size `, - :ref:`Border `, - :ref:`Text ` - - ``label`` - - *Description* : The text inside the button - - *Values*: String - - ``icon`` - - *Description*: The icon of the button - - *Values*: `Font awesome `_ symbol name - - -``textfield`` -............. - - A text field. The value of the text field can be stored on the context using the event ``input``. - See the :ref:`Context` section for more details. - - **Attributes** - - :ref:`Class `, - :ref:`Visibility `, - :ref:`Grid `, - :ref:`Relative and Absolute `, - :ref:`Direction `, - :ref:`Color `, - :ref:`Size `, - :ref:`Border `, - :ref:`Text ` - - ``placeholder`` - - *Description* : The text inside the textfield before it is filled - - *Values*: String - - -``dropdown-menu`` -................. - - A dropdown menu for single select. - - **Attributes** - - :ref:`Class `, - :ref:`Visibility `, - :ref:`Grid `, - :ref:`Relative and Absolute `, - :ref:`Direction `, - :ref:`Color `, - :ref:`Size `, - :ref:`Border ` - - ``selected`` - - *Description* : The value apearing as selected - - *Values*: String - -``dropdown-menu-item`` -...................... - - An item inside a dropdown menu. Must be contained in a dropdown menu. - - **Attributes** - - :ref:`Class `, - :ref:`Visibility `, - :ref:`Grid `, - :ref:`Relative and Absolute `, - :ref:`Direction `, - :ref:`Color `, - :ref:`Size `, - :ref:`Border ` - - ``label`` - - *Description* : The text inside the item - - *Values*: String - -``canvas`` -........... - - A canvas to render images. - - Canvas can be used to render clingraph images, see :ref:`ClingraphBackend` for details. - - **Attributes** - - :ref:`Class `, - :ref:`Visibility `, - :ref:`Grid `, - :ref:`Relative and Absolute `, - :ref:`Direction ` - - ``image`` - - *Description* : The local path to the image - - *Values*: String - -Creating Your Own Frontend --------------------------- - -.. warning:: - Under construction. Sorry :). - - But feel free to contribute to the AngularFrontend with new components! - - - - - diff --git a/docs/clinguin/frontends/AngularFrontend.rst b/docs/clinguin/frontends/AngularFrontend.rst new file mode 100644 index 00000000..c63a44fc --- /dev/null +++ b/docs/clinguin/frontends/AngularFrontend.rst @@ -0,0 +1,477 @@ +AngularFrontend +--------------- + +This frontend was developed using `Angular `_. +For styling, it uses the `bootstrap `_ library with `Angular-Boostrap `_. +Thus, providing beautiful components out of the box by giving access to Bootstrap classes for styling. +For contributing with new components take a look at the :ref:`Development` section. + +.. admonition:: Examples + + + * `Angular Examples `_ + +.. tip:: + + It implements most of the elements and attributes of the TkinterFrontend. + So you can also check the Tkinter Syntax as explaned above and try setting those values. + +Atributes ++++++++++ + +.. note:: + + Any attribute that is passed that does not fall under this list or the specific attributes of the element, + will be set as a plain html style in the component + + +Class +..... + +The class atribute ``class`` will add a `bootstrap class `_ +to any element. +This attribute can apear multiple times. + +.. tip:: + + **Simplify, use classes!** + + It is encouranged to use classes for styling with the predefined colors. + Must of the attributes found below can be replaced by a bootstrap class. + + Not only that but you can set multiple classes in the same ASP rule using + + ``attr(ID,class,(C1;C2;...))`` + + + +Positioning +............ + +.. _Child layout: + +**Child layout** + +``child_layout`` + *Description*: With this attribute one can define the layout of the children, i.e. how they are positioned. + + *Values*: For the child-layout four different options exists: + - ``flex`` (default, tries to do it automatically) + - ``grid`` (grid-like-specification) + - ``absstatic`` (if one wants to specify the position with absolute-pixelcoordinates) + - ``relstatic`` (if one wants to specify the position with relative-pixel coordinates(from 0 to 100 percent, where 0 means left/top and 100 means right/bottom)). + + They can either bespecified via a clingo symbol or via a string (string is case-insensitive). + + +.. _Grid: + +**Grid** + +``grid_column`` + *Description*: With this attribute one can define in which column the element shall be positioned. + + *Values*: Integer + +``grid_row`` + *Description*: With this attribute one can define in which row the element shall be positioned. + + *Values*: Integer + +``grid_column_span`` + *Description*: With this attribute one can define, that the elements stretches over several columns. + + *Values*: Integer + +``grid_row_span`` + *Description*: With this attribute one can define, that the elements stretches over several rows. + + *Values*: Integer + + + +.. _Relative and Absolute: + +**Relative and Absolute** + +``pos_x`` + *Description*: With this attribute one sets the x-position of the element - it depends on the parents ``child-layout`` how this is defined (either pixels, relative as a percentage, ...). + + *Values*: Integer + +``pos_y`` + *Description*: With this attribute one sets the y-position of the element - it depends on the parents ``child-layout`` how this is defined (either pixels, relative as a percentage, ...). + + *Values*: Integer + + +.. _Direction: + +**Direction** + +.. tip :: + + Try using `boostrap positioning `_ instead. + + +``flex_direction`` + *Description*: With this attribute one can set the ``direction`` (i.e., where it gets placed) of anelement which root has a specified flex layout. + + *Values*: For the flex-direction type two possible values exist: + - ``column`` (vertical alignment) + - ``row`` (horizontal alignment). + +Style +..... + +.. _Color: + +**Color** + +.. tip :: + + Try using `boostrap colors `_ instead. + + +``background_color`` + *Description*: With this attribute one can define the background-color of the element. + + *Values*: Color + +``foreground_color`` + *Description*: With this attribute one can set the foreground-color of the element. + + *Values*: Color + +``border_color`` + *Description*: With this attribute one may set the border color. + + *Values*: Color + +``on_hover`` + *Description*: With this attribute one can enable or disable on-hover features for the element. + + *Values*: For the boolean type, either true or false are allowed - either as string or as a clingo-symbol. If one provides it as a string, it is case-insensitive. + +``on_hover_background_color`` + *Description*: With this attribute one can set the background color the element shall have, when on_hover is enabled. + + *Values*: Color + +``on_hover_foreground_color`` + *Description*: With this attribute one can set the forground color the element shall have, when on_hover is eneabled. + + *Values*: Color + +``on_hover_border_color`` + *Description*: With this attribute one can set the color the border of the element shall have, when on_hover is enabled. + + *Values*: Color + + +.. _Size: + +**Size** + +``height`` + *Description*: With this attribute one can set the height in pixels of the element. + + *Values*: Integer + +``width`` + *Description*: With this attribute one can set the width in pixels of the element. + + *Values*: Integer + + +.. _Border: + +**Border** + +.. tip :: + + Try using `boostrap borders `_ instead. + +``border_width`` + *Description*: With this attribute one defines the width of the border in pixels. + + *Values*: Integer + +``border_color`` + *Description*: With this attribute one may set the border color. + + *Values*: Color + +.. _Visibility: + +**Visibility** + +``visibility`` + *Description*: Sets the visibility of an element. It can be used to show things like a modal or a container using the update functionality + + *Values*: The visibility, options are: + - ``visible``: To show the element + - ``hidden``: To hide the element + +.. _Text: + +**Text** + +.. tip :: + + Try using `boostrap text `_ style instead. + + +Elements +++++++++ + + +``window`` +.......... + +The main window of the UI. It is necesary to especify exacly one element of this type. + +``menu-bar`` +............ + +The menu bar that apear on top. +Notice that any button which is a children of this element will be placed as part of the menu. + +**Attributes** + +``icon`` + *Description*: The main icon of the application + + *Values*: `Font awesome `_ symbol name + +``title`` + *Description*: The title shown in the uper lext corner + + *Values*: String + + +``message`` +............ + +A message shown to the user in the bottom. Corresponds to a `boostrap alert `_. +It must always be contained in the window element. + +This element is also used internally to send messages from the server to the UI. + +**Attributes** + +:ref:`Visibility ` + + +``type`` + *Description*: With this attribute one can set the look + + *Values*: For the popup-types three different options exists: 'info' (Default information message),'warning' and 'error' + +``title`` + *Description*: With this attribute one can set the title of the alert. + + *Values*: String, can either be specified as a string or if it is simple as a symbol. + +``message`` + *Description*: With this attribute one can set the message of the alert. + + *Values*: String, can either be specified as a string or if it is simple as a symbol. + + +``context-menu`` +................ + + +A context menu that will open in the position of the click. +It must always be contained in the window element. +All buttons inside this element will apear as options. + + +**Attributes** + + :ref:`Visibility ` + +``modal`` +......... + + +A modal pop-up window. +Implemented using `boostrap modals `_. +It must always be contained in the window element. + +**Attributes** + +:ref:`Class `, +:ref:`Visibility ` + +``title`` + *Description*: The title of the modal + + *Values*: String + +``container`` +............. + +A container for defining layout. +Implemented using `boostrap modals `_. + +**Attributes** + +:ref:`Class `, +:ref:`Visibility `, +:ref:`Child layout `, +:ref:`Grid `, +:ref:`Relative and Absolute `, +:ref:`Direction `, +:ref:`Color `, +:ref:`Size `, +:ref:`Border `, +:ref:`Text ` + +``title`` + *Description*: The title of the modal + + *Values*: String + +``button`` +.......... + +A button. +Implemented using `boostrap buttons `_. + +**Attributes** + +:ref:`Class `, +:ref:`Visibility `, +:ref:`Grid `, +:ref:`Relative and Absolute `, +:ref:`Direction `, +:ref:`Color `, +:ref:`Size `, +:ref:`Border `, +:ref:`Text ` + +``label`` + *Description*: The text inside the button + + *Values*: String + + ``icon`` + *Description*: The icon of the button + + *Values*: `Font awesome `_ symbol name + +``label`` +......... + +A label. + +**Attributes** + +:ref:`Class `, +:ref:`Visibility `, +:ref:`Grid `, +:ref:`Relative and Absolute `, +:ref:`Direction `, +:ref:`Color `, +:ref:`Size `, +:ref:`Border `, +:ref:`Text ` + +``label`` + *Description*: The text inside the button + + *Values*: String + +``icon`` + *Description*: The icon of the button + + *Values*: `Font awesome `_ symbol name + + +``textfield`` +............. + +A text field. The value of the text field can be stored on the context using the event ``input``. +See the :ref:`Context` section for more details. + +**Attributes** + +:ref:`Class `, +:ref:`Visibility `, +:ref:`Grid `, +:ref:`Relative and Absolute `, +:ref:`Direction `, +:ref:`Color `, +:ref:`Size `, +:ref:`Border `, +:ref:`Text ` + +``placeholder`` + *Description*: The text inside the textfield before it is filled + + *Values*: String + + +``dropdown-menu`` +................. + +A dropdown menu for single select. + +**Attributes** + +:ref:`Class `, +:ref:`Visibility `, +:ref:`Grid `, +:ref:`Relative and Absolute `, +:ref:`Direction `, +:ref:`Color `, +:ref:`Size `, +:ref:`Border ` + +``selected`` + *Description*: The value apearing as selected + + *Values*: String + +``dropdown-menu-item`` +...................... + +An item inside a dropdown menu. Must be contained in a dropdown menu. + +**Attributes** + +:ref:`Class `, +:ref:`Visibility `, +:ref:`Grid `, +:ref:`Relative and Absolute `, +:ref:`Direction `, +:ref:`Color `, +:ref:`Size `, +:ref:`Border ` + +``label`` + *Description*: The text inside the item + + *Values*: String + +``canvas`` +........... + +A canvas to render images. + +Canvas can be used to render clingraph images, see :ref:`ClingraphBackend` for details. + +**Attributes** + +:ref:`Class `, +:ref:`Visibility `, +:ref:`Grid `, +:ref:`Relative and Absolute `, +:ref:`Direction ` + +``image`` + *Description*: The local path to the image + + *Values*: String \ No newline at end of file diff --git a/docs/clinguin/frontends/TkinterFrontend.rst b/docs/clinguin/frontends/TkinterFrontend.rst new file mode 100644 index 00000000..4c3b3a83 --- /dev/null +++ b/docs/clinguin/frontends/TkinterFrontend.rst @@ -0,0 +1,21 @@ +TkinterFrontend +--------------- + +This frontend uses the standard Python interface `tkinter `_ to generate a UI. + +.. admonition:: Examples + + + * `Tkinter Examples `_ + +One can look up the available elements, with the corresponding attributes and callback actions using: + +.. code-block:: bash + + $ clinguin client-server --frontend-syntax + +If one is also interested in what values one might set, one can also look at the full syntax: + +.. code-block:: bash + + $ clinguin client-server --frontend-syntax-full \ No newline at end of file diff --git a/docs/clinguin/frontends/index.rst b/docs/clinguin/frontends/index.rst new file mode 100644 index 00000000..d6c0aa9f --- /dev/null +++ b/docs/clinguin/frontends/index.rst @@ -0,0 +1,29 @@ +Frontends +######### + +The frontends listed here are provided with clinguin. Each frontend allows different element types, arguments, and events. + +The source code for the frontends can be found on `GitHub `_. + + + + + +Built-in Frontends +++++++++++++++++++ + +.. toctree:: + :maxdepth: 1 + + TkinterFrontend.rst + AngularFrontend.rst + + +Creating Your Own Frontend ++++++++++++++++++++++++++++ + +.. warning:: + Under construction. Sorry :). + + But feel free to contribute to the AngularFrontend with new components! + diff --git a/docs/clinguin/reference.rst b/docs/clinguin/reference.rst deleted file mode 100644 index bc7d6357..00000000 --- a/docs/clinguin/reference.rst +++ /dev/null @@ -1,525 +0,0 @@ -=============== -Reference Guide -=============== - -This guide explains the internal workflow of `clinguin` and all its concepts. -The full workflow of the system is shown in the figure below. -All components of the diagram are explained in detail in this guide. - -.. note:: - - In this diagram, operations are marked in gray, states corresponding to sets of facts are depicted in green, and input files appear in red. - -.. figure:: ../workflow.png - - ------------------------------------------------------------------------------------- - -Structure -######### - -****** -Server -****** - - .. figure:: ../server.png - - The server is responsible for executing clingo and computing the information required to define the UI. This process unfolds in two distinct steps: - - 1. The :ref:`domain-state` is computed using the domain-specific encodings difined in the :ref:`domain-files`. These information include user-selected atoms, potential selections, and inferred atoms. - 2. The server utilizes the provided UI encoding to generate the :ref:`ui-state`, defining the layout, style, and functionality of the interface. - - To allow flexibility, further separation is done to have interchangeable functionalities. - - **Backend** - - - The part of the server that defines the control and functionality, allowing users to interact with the clingo control in different ways. - It offers the option to define and overwrite operations, as well as customize how the UI is updated and the contextual information in the :ref:`domain-state`. - Users can create their own Backend to increase functionality (:ref:`Creating your own backend`). - - We provide the following :ref:`Backends` with the system: - - * *ClingoBackend*: Basic clingo functionality using single-shot solving - * *ClingoMultishotBackend*: clingo functionality using multi-shot solving - * *ClingraphBackend*: ClingoMultishotBackend enhanced with the option to render and interact with Clingraph images - * *ExplanationBackend*: ClingoMultishotBackend enhanced with explanation functionalities via Minimal Unsatisfiable Cores - * *ClingoDLBackend*: ClingoMultishotBackend enhanced with `clingod-dl `_ - - - -****** -Client -****** - - .. figure:: ../client.png - - The client is responsible for rendering the UI and responding to the user's actions. - When it is loaded, it requests the :ref:`ui-state` from the server. - Upon receiving the :ref:`ui-state` in JSON format (:ref:`JSON UI`), the client utilizes a front-end language to render the corresponding UI. - - To allow flexibility, further separation is done to have interchangeable UIs and functionalities. - - **Frontend** - - The part of the client that generates the layout based on the :ref:`JSON UI` and displays the UI. Users can create their own Frontend to have a different view (:ref:`Creating your own frontend`). - - We provide the following :ref:`Frontends` with the system: - - * *AngularFrontend*: UI using Angular to generate a web interface - * *TkinterFrontend*: UI using Tkinter an OS-dependent interface - ------------------------------------------------------------------------------------- - -Input -##### - - - -************ -domain-files -************ - - .. figure:: ../domfiles.png - - The domain-specific ASP encodings that will generate solutions to the problem (including the instance). - These files will be used by the :ref:`domain-control`. - They are provided when starting the server via the command line in argument ``--domain-files``. - -************ -ui-files -************ - - .. figure:: ../uifiles.png - - The encoding that will generate the :ref:`ui-state` using the :ref:`domain-state` as input. - They are provided when starting the server via the command line in argument ``--ui-files``. - - ------------------------------------------------------------------------------------- - -State -##### - -States are sets of ASP facts that are used to define diferent aspects of the system. - - -******** -ui-state -******** - - .. figure:: ../uistate.png - - A User Interface is defined in `clinguin` using the three predicates below. - These facts are generated by calling clingo with the :ref:`domain-state` and the provided :ref:`ui-files`. - - .. note:: - The available element types, attributes, events, and actions will vary depending on the frontend. See the details for each front end in the :ref:`Frontends` section. - - - * ``elem(ID, TYPE, PARENT)`` - - Elements define building blocks of the UI. - - * ``ID`` Identifies the element for further references. - - * ``TYPE`` The type of element (``window``, ``container``, ``button`` etc). - - * ``PARENT`` The id of the parent element. The identifier ``root`` is used as the root element of the UI. - - - * ``attr(ID, KEY, VALUE)`` - - Attributes define the style of the UI. - - * ``ID`` Identifier of the element that the attribute will be set to. - - * ``KEY`` The name of the attribute. Available attributes depend on the element type and the frontend. - - * ``VALUE`` The value of the attribute. - - - * ``when(ID, EVENT, ACTION, OPERATION)`` - - Actions define the interactivity of the UI. Multiple actions are allowed, as explained below. - - - * ``ID`` Identifier of the element that the user interacted with. - - * ``EVENT`` The event that is being triggered, such as ``click``, ``hover``, ``input``, etc. Each element type allows different events. - - * ``ACTION`` The action performed. - - * ``call`` Calls the server to perform an operation. - * ``update`` Updates the attribute of another element without any calls to the server. - * ``context`` Updates the internal context that will be passed to the server on the following call actions. See :ref:`Context` for more details. - - * ``OPERATION`` The operation accounts for the information that the action requires for its execution. - - * ``ACTION`` = ``call`` The operation corresponds to a function available in the :ref:`Backends`. The function call is represented as a predicate, for instance ``add_assumption(a)`` or ``next_solution``. - * ``ACTION`` = ``update`` The operation will be a tuple of size three ``(ID', KEY, VALUE)`` where ``ID'`` is the identifier of the element whose value for attribute ``KEY`` will be updated to ``VALUE``. Notice that ``ID'`` might be different than ``ID``. - * ``ACTION`` = ``context`` The operation will be a tuple ``(KEY, VALUE)``, which will update the key ``KEY`` in the context dictionary to ``VALUE``. See the :ref:`Context` section for detail information on how to use the context. - - - **Multiple actions** - - If multiple occurrences of the predicate ``when`` are present for the same element and event. All of them will be executed. First, the updates will be performed, followed by context changes and finally server calls. Within each type of action, no order can be assured. - - In the case of multiple appearances of ``call``, a single call will be placed to the server with the information to execute all actions in any order. - - .. admonition:: Example - :class: example - - When ``button1`` is clicked, the server will receive the instruction to execute two operations: adding assumption ``a`` and adding assumption ``b`` in any order. For a more evolved example of this feature, see the `jobshop example `_. - - .. code-block:: - - when(button1, click, call, add_assumption(a)). - when(button1, click, call, add_assumption(b)). - - - To impose an order, the operation provided must be a tuple, in which case the order of execution is defined by the tuple. - - .. admonition:: Example - :class: example - - This example below will make sure that assumption ``a`` is added before computing a solution. - - .. code-block:: - - when(button1, click, call, (add_assumption(a), next_solution)). - -************ -domain-state -************ - - .. figure:: ../domstate.png - - A set of facts defining the state of the domain, which will be used as input to the :ref:`ui-files`. - These facts are generated by multiple domain-state constructors defined by the backend. - Each backend will define its own domain-state constructors which can involve solve calls or any other information. - The domain-state constructors can be found in :ref:`backends`. - In what follows we explain in detail the list of base constructors used in the :ref:`ClingoMultishotBackend` - - The domain state of :ref:`ClingoMultishotBackend` will provide a model and some useful reasoning information; - when creating a UI one usually needs to reason with what is still *possibly* part of the solution and what is *necessarily* in the solution. - In ASP terms, we use the following brave and cautious reasoning to provide this information as explained below. - - **Model** - - The atoms of the first computed model are added directly to the :ref:`domain-state`. When the user is browsing the solutions, this model will change accordingly. - - **Brave consequences** - - Atoms that are in any stable models (Union) of the :ref:`domain-control`. These atoms are part of the :ref:`domain-state` enclosed in predicate ``_any``. - We usually employ brave consequences to create elements where we want to provide the user with all the possible options. For instance, in a dropdown menu. By using brave consequences, we make sure that these selections lead to a valid answer. - - .. admonition:: Example - :class: example - - Consider the following encoding, where either ``p(1)`` or ``p(2)`` can be selected. - - .. code-block:: - - 1{p(1);p(2)}1. - - We have two stable models: `{p(1)}` and `{p(2)}`, so brave consequences (union) are `{p(1), p(2)}`. - Therefore the following atoms will be added to the :ref:`domain-state`. - - .. code-block:: - - _any(p(1)). - _any(p(2)). - - - **Cautious consequences** - - Atoms that are in all stable models (intersection) of the :ref:`domain-control`. These atoms are part of the :ref:`domain-state` enclosed in predicate ``_all``. - We usually employ cautious consequences when we want to show the user any inferences done by the solver. For instance, the selected value of a dropdown menu. Naturally, assumptions made by the user will impact these consequences. - - - .. admonition:: Example - :class: example - - Consider the following encoding, where either ``p(1)`` or ``p(2)`` can be selected. - - .. code-block:: - - {p(1);p(2);p(3)}. - :- p(1). - - We have one stable model: `{p(1)}`. - Therefore the following atoms will be added to the :ref:`domain-state`. - - .. code-block:: - - _all(p(1)). - - - - **_clinguin_browsing/0** - - This constant is present when the user is browsing models, meaning that the ``next()`` operation has been requested. It can be used to decide whether the UI must show the current model. - - .. admonition:: Example - :class: example - - In the `sudoku example `_, presented in section :ref:`Basic Usage`, the following lines define the selected value of a dropdown menu. When browsing is active, the value of the cell in the given model ``sudoku(X,Y,V)`` defines the selected value, otherwise, a selected option will be defined only for values that are forced by the encoding ``_all`` (see :ref:`domain-state`). - - .. code-block:: - - attr(dd(X,Y),selected,V):-_all(sudoku(X,Y,V)). - attr(dd(X,Y),selected,V):-sudoku(X,Y,V), _clinguin_browsing. - - **_clinguin_unsat/0** - - This constant is present if the :ref:`domain-control` gave an unsatisfiable response. - - - **_clinguin_assume/1** - - These atoms give information about what has been assumed by the user via the backend instructions. - - .. admonition:: Example - :class: example - - In the `sudoku example `_, presented in section :ref:`Basic Usage`, the following lines define the color of the selected value of a dropdown menu. - When the value was set by the user, which we can know if ``_clinguin_assume(sudoku(X,Y,V))`` is part of the :ref:`domain-state`, then we show it using the primary color (blue). Otherwise, the value was inferred by the system and we show it using the info color (gray). - - .. code-block:: - - attr(dd(X,Y),class,("text-primary")):-_clinguin_assume(sudoku(X,Y,V)). - attr(dd(X,Y),class,("text-info")):-_all(sudoku(X,Y,V)), not _clinguin_assume(sudoku(X,Y,V)). - - **_clinguin_conext/2** - - These atoms provide access to the context information available in the frontend when the :ref:`domain-state` is generated. The first argument is the key, and the second one is the value. For more information check the :ref:`Context` section. - ------------------------------------------------------------------------------------- - -Control -####### - -************** -domain-control -************** - - .. figure:: ../domcontrol.png - - - The *Clingo* control that will be handled by the Backend. - It includes the domain files and can be accessed by the actions performed by the user. - Most backends handle this control in a multi-shot fashion, where grounding is only done once (or on demand), and assumptions, as well as externals, are used to alter the solving. The domain-control is used to generate the :ref:`domain-state`. - -************** -ui-control -************** - - .. figure:: ../uicontrol.png - - - The *Clingo* control that will be used to compute the :ref:`ui-state` using the :ref:`ui-files`. - This control is initialized every time the UI is updated. - - ---------------------------------------------------------------------------------- - -Communication -############# - -**** -GET -**** - .. figure:: ../get.png - - When the UI is first loaded and in every reload, the client will do a ``GET`` request which will update the UI. - -**** -POST -**** - - .. figure:: ../post.png - - When the user triggers as event that is associiated with a ``call`` action, the client will do a ``POST`` request. - This request will include the selected operations and the context. - - -********** -Operations -********** - - .. figure:: ../operation.png - - The operations are defined by the backend. These operations will interact with the domain control while performing all the required changes. - Each backend will define an available list of operations. These lists can be found in :ref:`Backends`. - - -******** -Context -******** - - .. figure:: ../context.png - - - The context can be used to store information provided by the user before calling the server. For instance, it can store the input of a text field, or the value of a checkbox. Therefore, it is usefull for creating input forms within the UI. Internally, the context is represented by a dictionary in the client and it can be accesed in three ways. - - .. warning:: - Context information is only available for web frontends and not for Tkinter. - - - **Updates** - - The context information is updated using predicate ``when`` as described above. - - .. admonition:: Example - :class: example - - The context would be updated with the key-value pair `(agree, true)` when `button1` is clicked. - - .. code-block:: - - when(button1, click, context, (agree, true)). - - To use a value imputed by the user, such as for text fields, the special constant ``_value`` will hold the value of an input event. - - .. admonition:: Example - :class: example - - .. code-block:: - - when(textfield1, input, context, (t1_content, _value)). - - - **Substitution** - - The values of the context can be accessed for a direct substitution in the operation of a call. This is done with the special predicates ``_context_value/1`` and ``_context_value_optional/1``. The argument of these predicates is the key which will be substituted by the value before it is processed by the server. While ``_context_value/1`` will show an error in case there is no value for the provided key, ``_context_value_optional/1`` will leave the input optional, and in case there is no value present it is substitued by None. - - .. admonition:: Example - :class: example - - Example from the `ast example `_. - The key `selected_node` is set open clicking on a node and then this information is sustituted on the next line when the server is called to add an atom, which yeilds operation ``add_atom(show_children(X,true)))`` after the substitution, with ``X`` being the selected node. - - .. code-block:: - - when(node(X), click, context, (selected_node, X)):- node(X). - when(button1, click, call, add_atom(show_children(_context_value(selected_node),true))). - - **Access** - - All calls to the server will include the context as an argument. All backends will have access to this dictionary and can use its values for any operation. The provadided backends include the context information as part of the :ref:`domain-state` via predicate ``_clinguin_context(KEY,VALUE)``. Thus, giving the UI encoding access to the context at the time the call was made. Beware that changes in the context are not reflected in the UI encoding imidiatley, but only after calling the server and calculating the UI again. - - - .. warning:: - The context is erased after every call to the server. - - - .. tip:: - If some of the context wants to be preserved between calls to the server, it can be done manually in the UI encoding by using the event ``load`` of the ``window``. An example is provided below, which is used in the `ast example `_. - - .. code-block:: - - when(window, load, context, (selected_node, X)):- _clinguin_context(selected_node, X). - - - - -******** -JSON UI -******** - - .. figure:: ../json.png - - - The :ref:`ui-state` is represented by a JSON to comunicate between client and server. This JSON is generated in a herachical fashion where each element apears with the following form. - - .. code-block:: - - { - "id": , - "type": , - "parent": , - "attributes": - [ - { - "id": , - "key": , - "value": - }, - ... - ], - "when": - [ - { - "id": , - "event": , - "interaction_type": , - "policy": - } - ], - "children": [] - } - - - .. admonition:: Example - :class: example - - The following :ref:`ui-state` the corresponding JSON UI can be found below. - - - .. code-block:: - - elem(w, window, root). - elem(b1, button, w). - attr(b1, label, "Button 1"). - when(b1, click, call, next_solution). - - - .. code-block:: - - { - "id":"root", - "type":"root", - "parent":"root", - "attributes":[], - "when":[], - "children":[ - { - "id":"w", - "type":"window", - "parent":"root", - "attributes":[], - "when":[], - "children":[ - { - "id":"b1", - "type":"button", - "parent":"w", - "attributes":[ - { - "id":"b1", - "key":"label", - "value":"\"Button 1\"" - } - ], - "when":[ - { - "id":"b1", - "event":"click", - "interaction_type":"call", - "policy":"next_solution" - } - ], - "children":[] - } - ] - } - ] - } - - - - - - - diff --git a/docs/clinguin/reference/communication.rst b/docs/clinguin/reference/communication.rst new file mode 100644 index 00000000..b41ed249 --- /dev/null +++ b/docs/clinguin/reference/communication.rst @@ -0,0 +1,201 @@ + +Communication +############# + +**** +GET +**** +.. figure:: ../../get.png + +When the UI is first loaded and in every reload, the client will do a ``GET`` request which will update the UI. + +**** +POST +**** + +.. figure:: ../../post.png + +When the user triggers as event that is associiated with a ``call`` action, the client will do a ``POST`` request. +This request will include the selected operations and the context. + + +********** +Operations +********** + +.. figure:: ../../operation.png + +The operations are defined by the backend. These operations will interact with the domain control while performing all the required changes. +Each backend will define an available list of operations. These lists can be found in :ref:`Backends`. + + +******** +Context +******** + +.. figure:: ../../context.png + + +The context can be used to store information provided by the user before calling the server. For instance, it can store the input of a text field, or the value of a checkbox. Therefore, it is usefull for creating input forms within the UI. Internally, the context is represented by a dictionary in the client and it can be accesed in three ways. + +.. warning:: + + Context information is only available for web frontends and not for Tkinter. + + +**Updates** + +The context information is updated using predicate ``when`` as described above. + +.. admonition:: Example + + + The context would be updated with the key-value pair `(agree, true)` when `button1` is clicked. + + .. code-block:: + + when(button1, click, context, (agree, true)). + +To use a value imputed by the user, such as for text fields, the special constant ``_value`` will hold the value of an input event. + +.. admonition:: Example + + + .. code-block:: + + when(textfield1, input, context, (t1_content, _value)). + + +**Substitution** + +The values of the context can be accessed for a direct substitution in the operation of a call. This is done with the special predicates ``_context_value/1`` and ``_context_value_optional/1``. The argument of these predicates is the key which will be substituted by the value before it is processed by the server. While ``_context_value/1`` will show an error in case there is no value for the provided key, ``_context_value_optional/1`` will leave the input optional, and in case there is no value present it is substitued by None. + +.. admonition:: Example + + + Example from the `ast example `_. + The key `selected_node` is set open clicking on a node and then this information is sustituted on the next line when the server is called to add an atom, which yeilds operation ``add_atom(show_children(X,true)))`` after the substitution, with ``X`` being the selected node. + + .. code-block:: + + when(node(X), click, context, (selected_node, X)):- node(X). + when(button1, click, call, add_atom(show_children(_context_value(selected_node),true))). + +**Access** + +All calls to the server will include the context as an argument. All backends will have access to this dictionary and can use its values for any operation. The provadided backends include the context information as part of the :ref:`domain-state` via predicate ``_clinguin_context(KEY,VALUE)``. Thus, giving the UI encoding access to the context at the time the call was made. Beware that changes in the context are not reflected in the UI encoding imidiatley, but only after calling the server and calculating the UI again. + + +.. warning:: + The context is erased after every call to the server. + + +.. tip:: + If some of the context wants to be preserved between calls to the server, it can be done manually in the UI encoding by using the event ``load`` of the ``window``. An example is provided below, which is used in the `ast example `_. + + .. code-block:: + + when(window, load, context, (selected_node, X)):- _clinguin_context(selected_node, X). + + + + +******** +JSON UI +******** + +.. figure:: ../../json.png + + +The :ref:`ui-state` is represented by a JSON to comunicate between client and server. This JSON is generated in a herachical fashion where each element apears with the following form. + +.. code-block:: + + { + "id": , + "type": , + "parent": , + "attributes": + [ + { + "id": , + "key": , + "value": + }, + ... + ], + "when": + [ + { + "id": , + "event": , + "interaction_type": , + "policy": + } + ], + "children": [] + } + + +.. admonition:: Example + + + The following :ref:`ui-state` the corresponding JSON UI can be found below. + + + .. code-block:: + + elem(w, window, root). + elem(b1, button, w). + attr(b1, label, "Button 1"). + when(b1, click, call, next_solution). + + + .. code-block:: + + { + "id":"root", + "type":"root", + "parent":"root", + "attributes":[], + "when":[], + "children":[ + { + "id":"w", + "type":"window", + "parent":"root", + "attributes":[], + "when":[], + "children":[ + { + "id":"b1", + "type":"button", + "parent":"w", + "attributes":[ + { + "id":"b1", + "key":"label", + "value":"\"Button 1\"" + } + ], + "when":[ + { + "id":"b1", + "event":"click", + "interaction_type":"call", + "policy":"next_solution" + } + ], + "children":[] + } + ] + } + ] + } + + + + + + + diff --git a/docs/clinguin/reference/control.rst b/docs/clinguin/reference/control.rst new file mode 100644 index 00000000..3b7fc480 --- /dev/null +++ b/docs/clinguin/reference/control.rst @@ -0,0 +1,26 @@ + +Control +####### + +************** +domain-control +************** + +.. figure:: ../../domcontrol.png + + +The *Clingo* control that will be handled by the Backend. +It includes the domain files and can be accessed by the actions performed by the user. +Most backends handle this control in a multi-shot fashion, where grounding is only done once (or on demand), and assumptions, as well as externals, are used to alter the solving. The domain-control is used to generate the :ref:`domain-state`. + +************** +ui-control +************** + +.. figure:: ../../uicontrol.png + + +The *Clingo* control that will be used to compute the :ref:`ui-state` using the :ref:`ui-files`. +This control is initialized every time the UI is updated. + + diff --git a/docs/clinguin/reference/index.rst b/docs/clinguin/reference/index.rst new file mode 100644 index 00000000..fff63a02 --- /dev/null +++ b/docs/clinguin/reference/index.rst @@ -0,0 +1,24 @@ +=============== +Reference Guide +=============== + +This guide explains the internal workflow of `clinguin` and all its concepts. +The full workflow of the system is shown in the figure below. +All components of the diagram are explained in detail in this guide. + + +.. figure:: ../../workflow.png + +.. note:: + + In this diagram, operations are marked in gray, states corresponding to sets of facts are depicted in green, and input files appear in red. + + +.. toctree:: + + structure.rst + input.rst + state.rst + control.rst + communication.rst + diff --git a/docs/clinguin/reference/input.rst b/docs/clinguin/reference/input.rst new file mode 100644 index 00000000..54914666 --- /dev/null +++ b/docs/clinguin/reference/input.rst @@ -0,0 +1,24 @@ +Input +##### + + + +************ +domain-files +************ + +.. figure:: ../../domfiles.png + +The domain-specific ASP encodings that will generate solutions to the problem (including the instance). +These files will be used by the :ref:`domain-control`. +They are provided when starting the server via the command line in argument ``--domain-files``. + +************ +ui-files +************ + +.. figure:: ../../uifiles.png + +The encoding that will generate the :ref:`ui-state` using the :ref:`domain-state` as input. +They are provided when starting the server via the command line in argument ``--ui-files``. + diff --git a/docs/clinguin/reference/state.rst b/docs/clinguin/reference/state.rst new file mode 100644 index 00000000..1c9614a3 --- /dev/null +++ b/docs/clinguin/reference/state.rst @@ -0,0 +1,197 @@ + +State +##### + +States are sets of ASP facts that are used to define diferent aspects of the system. + + +******** +ui-state +******** + +.. figure:: ../../uistate.png + +A User Interface is defined in `clinguin` using the three predicates below. +These facts are generated by calling clingo with the :ref:`domain-state` and the provided :ref:`ui-files`. + +.. note:: + + The available element types, attributes, events, and actions will vary depending on the frontend. See the details for each front end in the :ref:`Frontends` section. + + +- ``elem(ID, TYPE, PARENT)`` + +Elements define building blocks of the UI. + +- ``ID`` Identifies the element for further references. + +- ``TYPE`` The type of element (``window``, ``container``, ``button`` etc). + +- ``PARENT`` The id of the parent element. The identifier ``root`` is used as the root element of the UI. + + +- ``attr(ID, KEY, VALUE)`` + +Attributes define the style of the UI. + +- ``ID`` Identifier of the element that the attribute will be set to. + +- ``KEY`` The name of the attribute. Available attributes depend on the element type and the frontend. + +- ``VALUE`` The value of the attribute. + + +- ``when(ID, EVENT, ACTION, OPERATION)`` + +Actions define the interactivity of the UI. Multiple actions are allowed, as explained below. + + +- ``ID`` Identifier of the element that the user interacted with. + +- ``EVENT`` The event that is being triggered, such as ``click``, ``hover``, ``input``, etc. Each element type allows different events. + +- ``ACTION`` The action performed. + - ``call`` Calls the server to perform an operation. + - ``update`` Updates the attribute of another element without any calls to the server. + - ``context`` Updates the internal context that will be passed to the server on the following call actions. See :ref:`Context` for more details. + +- ``OPERATION`` The operation accounts for the information that the action requires for its execution. + - ``ACTION`` = ``call`` The operation corresponds to a function available in the :ref:`Backends`. The function call is represented as a predicate, for instance ``add_assumption(a)`` or ``next_solution``. + - ``ACTION`` = ``update`` The operation will be a tuple of size three ``(ID', KEY, VALUE)`` where ``ID'`` is the identifier of the element whose value for attribute ``KEY`` will be updated to ``VALUE``. Notice that ``ID'`` might be different than ``ID``. + - ``ACTION`` = ``context`` The operation will be a tuple ``(KEY, VALUE)``, which will update the key ``KEY`` in the context dictionary to ``VALUE``. See the :ref:`Context` section for detail information on how to use the context. + + +**Multiple actions** + +If multiple occurrences of the predicate ``when`` are present for the same element and event. All of them will be executed. First, the updates will be performed, followed by context changes and finally server calls. Within each type of action, no order can be assured. + +In the case of multiple appearances of ``call``, a single call will be placed to the server with the information to execute all actions in any order. + +.. admonition:: Example + + + When ``button1`` is clicked, the server will receive the instruction to execute two operations: adding assumption ``a`` and adding assumption ``b`` in any order. For a more evolved example of this feature, see the `jobshop example `_. + + .. code-block:: + + when(button1, click, call, add_assumption(a)). + when(button1, click, call, add_assumption(b)). + + +To impose an order, the operation provided must be a tuple, in which case the order of execution is defined by the tuple. + +.. admonition:: Example + + + This example below will make sure that assumption ``a`` is added before computing a solution. + + .. code-block:: + + when(button1, click, call, (add_assumption(a), next_solution)). + +************ +domain-state +************ + +.. figure:: ../../domstate.png + +A set of facts defining the state of the domain, which will be used as input to the :ref:`ui-files`. +These facts are generated by multiple domain-state constructors defined by the backend. +Each backend will define its own domain-state constructors which can involve solve calls or any other information. +The domain-state constructors can be found in :ref:`backends`. +In what follows we explain in detail the list of base constructors used in the :ref:`ClingoMultishotBackend` + +The domain state of :ref:`ClingoMultishotBackend` will provide a model and some useful reasoning information; +when creating a UI one usually needs to reason with what is still *possibly* part of the solution and what is *necessarily* in the solution. +In ASP terms, we use the following brave and cautious reasoning to provide this information as explained below. + +**Model** + +The atoms of the first computed model are added directly to the :ref:`domain-state`. When the user is browsing the solutions, this model will change accordingly. + +**Brave consequences** + +Atoms that are in any stable models (Union) of the :ref:`domain-control`. These atoms are part of the :ref:`domain-state` enclosed in predicate ``_any``. +We usually employ brave consequences to create elements where we want to provide the user with all the possible options. For instance, in a dropdown menu. By using brave consequences, we make sure that these selections lead to a valid answer. + +.. admonition:: Example + + + Consider the following encoding, where either ``p(1)`` or ``p(2)`` can be selected. + + .. code-block:: + + 1{p(1);p(2)}1. + + We have two stable models: `{p(1)}` and `{p(2)}`, so brave consequences (union) are `{p(1), p(2)}`. + Therefore the following atoms will be added to the :ref:`domain-state`. + + .. code-block:: + + _any(p(1)). + _any(p(2)). + + +**Cautious consequences** + +Atoms that are in all stable models (intersection) of the :ref:`domain-control`. These atoms are part of the :ref:`domain-state` enclosed in predicate ``_all``. +We usually employ cautious consequences when we want to show the user any inferences done by the solver. For instance, the selected value of a dropdown menu. Naturally, assumptions made by the user will impact these consequences. + + +.. admonition:: Example + + + Consider the following encoding, where either ``p(1)`` or ``p(2)`` can be selected. + + .. code-block:: + + {p(1);p(2);p(3)}. + :- p(1). + + We have one stable model: `{p(1)}`. + Therefore the following atoms will be added to the :ref:`domain-state`. + + .. code-block:: + + _all(p(1)). + + + +**_clinguin_browsing/0** + +This constant is present when the user is browsing models, meaning that the ``next()`` operation has been requested. It can be used to decide whether the UI must show the current model. + +.. admonition:: Example + + + In the `sudoku example `_, presented in section :ref:`Quick Start`, the following lines define the selected value of a dropdown menu. When browsing is active, the value of the cell in the given model ``sudoku(X,Y,V)`` defines the selected value, otherwise, a selected option will be defined only for values that are forced by the encoding ``_all`` (see :ref:`domain-state`). + + .. code-block:: + + attr(dd(X,Y),selected,V):-_all(sudoku(X,Y,V)). + attr(dd(X,Y),selected,V):-sudoku(X,Y,V), _clinguin_browsing. + +**_clinguin_unsat/0** + +This constant is present if the :ref:`domain-control` gave an unsatisfiable response. + + +**_clinguin_assume/1** + +These atoms give information about what has been assumed by the user via the backend instructions. + +.. admonition:: Example + + + In the `sudoku example `_, presented in section :ref:`Quick Start`, the following lines define the color of the selected value of a dropdown menu. + When the value was set by the user, which we can know if ``_clinguin_assume(sudoku(X,Y,V))`` is part of the :ref:`domain-state`, then we show it using the primary color (blue). Otherwise, the value was inferred by the system and we show it using the info color (gray). + + .. code-block:: + + attr(dd(X,Y),class,("text-primary")):-_clinguin_assume(sudoku(X,Y,V)). + attr(dd(X,Y),class,("text-info")):-_all(sudoku(X,Y,V)), not _clinguin_assume(sudoku(X,Y,V)). + +**_clinguin_conext/2** + +These atoms provide access to the context information available in the frontend when the :ref:`domain-state` is generated. The first argument is the key, and the second one is the value. For more information check the :ref:`Context` section. + diff --git a/docs/clinguin/reference/structure.rst b/docs/clinguin/reference/structure.rst new file mode 100644 index 00000000..44657c2d --- /dev/null +++ b/docs/clinguin/reference/structure.rst @@ -0,0 +1,53 @@ +Structure +######### + +****** +Server +****** + +.. figure:: ../../server.png + +The server is responsible for executing clingo and computing the information required to define the UI. This process unfolds in two distinct steps: + +1. The :ref:`domain-state` is computed using the domain-specific encodings difined in the :ref:`domain-files`. These information include user-selected atoms, potential selections, and inferred atoms. +2. The server utilizes the provided UI encoding to generate the :ref:`ui-state`, defining the layout, style, and functionality of the interface. + +To allow flexibility, further separation is done to have interchangeable functionalities. + +**Backend** + + +The part of the server that defines the control and functionality, allowing users to interact with the clingo control in different ways. +It offers the option to define and overwrite operations, as well as customize how the UI is updated and the contextual information in the :ref:`domain-state`. +Users can create their own Backend to increase functionality (:ref:`Creating your own backend`). + +We provide the following :ref:`Backends` with the system: + +* *ClingoBackend*: Basic clingo functionality using single-shot solving +* *ClingoMultishotBackend*: clingo functionality using multi-shot solving +* *ClingraphBackend*: ClingoMultishotBackend enhanced with the option to render and interact with Clingraph images +* *ExplanationBackend*: ClingoMultishotBackend enhanced with explanation functionalities via Minimal Unsatisfiable Cores +* *ClingoDLBackend*: ClingoMultishotBackend enhanced with `clingod-dl `_ + + + +****** +Client +****** + +.. figure:: ../../client.png + +The client is responsible for rendering the UI and responding to the user's actions. +When it is loaded, it requests the :ref:`ui-state` from the server. +Upon receiving the :ref:`ui-state` in JSON format (:ref:`JSON UI`), the client utilizes a front-end language to render the corresponding UI. + +To allow flexibility, further separation is done to have interchangeable UIs and functionalities. + +**Frontend** + +The part of the client that generates the layout based on the :ref:`JSON UI` and displays the UI. Users can create their own Frontend to have a different view (:ref:`Creating your own frontend`). + +We provide the following :ref:`Frontends` with the system: + +* *AngularFrontend*: UI using Angular to generate a web interface +* *TkinterFrontend*: UI using Tkinter an OS-dependent interface diff --git a/docs/clinguin/use.rst b/docs/clinguin/use.rst index c3f02035..ce0ec920 100644 --- a/docs/clinguin/use.rst +++ b/docs/clinguin/use.rst @@ -1,8 +1,8 @@ -Basic Usage +Quick Start =========== -We will use the `sudoku example `_ , and run it using the `ClingoMultishotBackend` and the `AngularFrontend`. +We will use the `sudoku example `_ , and run it using the :ref:`ClingoMultishotBackend` and the :ref:`AngularFrontend`. .. image:: ../../examples/angular/sudoku/out1.png @@ -18,37 +18,37 @@ Running clinguin **Client-Server** - To run `clinguin` one can the execute the following command: +To run `clinguin` one can the execute the following command: - .. code-block:: bash +.. code-block:: bash - $ clinguin client-server --domain-files examples/angular/sudoku/instance.lp examples/angular/sudoku/encoding.lp --ui-files examples/angular/sudoku/ui.lp --frontend AngularFrontend + $ clinguin client-server --domain-files examples/angular/sudoku/instance.lp examples/angular/sudoku/encoding.lp --ui-files examples/angular/sudoku/ui.lp --frontend AngularFrontend - After the execution, a Sudoku window in your browser should open, where one can play a round of Sudoku. +After the execution, a Sudoku window in your browser should open, where one can play a round of Sudoku. - The `client-server` option provided in the command line, states that both client and server shall be started at the same time, so it has the look and feel of a single program. If one wants to seperate `client` and `server`, one could start them in two shells. +The `client-server` option provided in the command line, states that both client and server shall be started at the same time, so it has the look and feel of a single program. If one wants to seperate `client` and `server`, one could start them in two shells. **Server** - .. code-block:: bash +.. code-block:: bash - $ clinguin server --domain-files examples/angular/sudoku/instance.lp examples/angular/sudoku/encoding.lp --ui-files examples/angular/sudoku/ui.lp + $ clinguin server --domain-files examples/angular/sudoku/instance.lp examples/angular/sudoku/encoding.lp --ui-files examples/angular/sudoku/ui.lp - The source and ui files are only specified for the server, the client does not need to care about this. As one can see, we have specified three files: ``instance.lp``, ``encoding.lp`` and ``ui.lp``. This is a common separation for `clinguin`, therefore one can at first experiment with the problem one is working on, and after that create a ui for the problem, to showcase, debug, etc. +The source and ui files are only specified for the server, the client does not need to care about this. As one can see, we have specified three files: ``instance.lp``, ``encoding.lp`` and ``ui.lp``. This is a common separation for `clinguin`, therefore one can at first experiment with the problem one is working on, and after that create a ui for the problem, to showcase, debug, etc. - When running the server one can further specify the *Backend* that should be used. See the :ref:`Backends` for more information. +When running the server one can further specify the *Backend* that should be used. See the :ref:`Backends` for more information. **Client** - .. code-block:: bash +.. code-block:: bash - $ clinguin client --frontend AngularFrontend + $ clinguin client --frontend AngularFrontend - The client does not need any files as input since it will ask the server for the information. +The client does not need any files as input since it will ask the server for the information. - When running the client one can further specify the *Frontend* that should be used. See the :ref:`Backends` for more information. See the :ref:`Backends` for more information. +When running the client one can further specify the *Frontend* that should be used. See the :ref:`Backends` for more information. See the :ref:`Backends` for more information. Understanding the UI encoding diff --git a/docs/conf.py b/docs/conf.py index 2a9bfe5d..48f5c52a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,13 +32,21 @@ # ones. extensions = [ 'nbsphinx', - 'sphinx_rtd_theme', + "sphinx.ext.extlinks", + "sphinx.ext.mathjax", + "sphinx.ext.todo", + "sphinx.ext.viewcode", 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.autosectionlabel', - 'sphinx.ext.intersphinx' + 'sphinx.ext.intersphinx', + 'furo.sphinxext', + "sphinx_copybutton", + # "sphinx_design", + # "sphinx_inline_tabs" ] + napoleon_include_init_with_doc = False napoleon_use_admonition_for_examples = False napoleon_use_admonition_for_references = True @@ -57,22 +65,33 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' +html_theme = 'furo' + +html_title = "clinguin" html_theme_options = { - 'canonical_url': '', # 'analytics_id': 'UA-XXXXXXX-1', # Provided by Google in your dashboard - 'logo_only': False, - 'display_version': True, - 'display_version': True, - 'prev_next_buttons_location': 'bottom', - 'style_external_links': False, + "light_logo": "logo-light-mode.png", + "dark_logo": "logo-dark-mode.png", + # 'style_external_links': False, # Toc options - 'collapse_navigation': True, - 'sticky_navigation': False, - 'navigation_depth': 4, - 'includehidden': True, - 'titles_only': False + # 'collapse_navigation': True, + # 'sticky_navigation': False, + # 'navigation_depth': 4, + # 'includehidden': True, + # 'titles_only': False + "footer_icons": [ + { + "name": "GitHub", + "url": "https://github.com/potassco/clinguin/blob/master", + "html": """ + + + + """, + "class": "", + }, + ] } html_css_files = [ diff --git a/docs/index.rst b/docs/index.rst index ebd8c8e7..46a1eeab 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,7 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Clinguin: Building User Interfaces in ASP +Clinguin: Building UIs in ASP ========================================= Clinguin enables ASP developers to create interactive User Interface (UI) prototypes using only ASP. @@ -43,20 +43,19 @@ Clinguin will use this encoding and the following ui encoding to construct the U .. image:: ../examples/angular/sudoku_basic/out3.png :width: 30% -For a more detailed explanation on how this code works take a look at the :ref:`Basic Usage` section. +For a more detailed explanation on how this code works take a look at the :ref:`Quick Start` section. .. note:: Clinguin is part the Potassco umbrella (which is the home of Clingo and the other ASP tools) .. toctree:: - :maxdepth: 2 - :caption: Contents: + :hidden: clinguin/installation clinguin/use.rst - clinguin/reference - clinguin/frontends - clinguin/backends + clinguin/reference/index.rst + clinguin/frontends/index.rst + clinguin/backends/index.rst clinguin/development diff --git a/docs/logo-dark-mode.png b/docs/logo-dark-mode.png new file mode 100644 index 00000000..81ed997a Binary files /dev/null and b/docs/logo-dark-mode.png differ diff --git a/docs/logo-light-mode.png b/docs/logo-light-mode.png new file mode 100644 index 00000000..d2ac73df Binary files /dev/null and b/docs/logo-light-mode.png differ diff --git a/docs/requirements.txt b/docs/requirements.txt index 8c29f67f..94c28aaa 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -9,6 +9,9 @@ uvicorn Pillow sphinx>=4.5.0 sphinx-rtd-theme==0.5.2 +sphinx_copybutton nbsphinx>=0.8.8 jinja2>=3.0.3 -clingo-dl \ No newline at end of file +clingo-dl +furo + diff --git a/examples/angular/jobshop/README.md b/examples/angular/jobshop/README.md index 0fb0984d..8a22596f 100644 --- a/examples/angular/jobshop/README.md +++ b/examples/angular/jobshop/README.md @@ -1,4 +1,4 @@ -## Placement +## Jobshop - **Backend**: `ClingoDLBackend` - **Frontend**: `AngularFrontend` diff --git a/examples/angular/style/README.md b/examples/angular/style/README.md index bdf3d3fd..09332447 100644 --- a/examples/angular/style/README.md +++ b/examples/angular/style/README.md @@ -1,4 +1,4 @@ -## Placement +## Style - **Backend**: `ClingoMultishotBackend` - **Frontend**: `AngularFrontend` diff --git a/setup.cfg b/setup.cfg index 7c2ed08a..3b0795a4 100644 --- a/setup.cfg +++ b/setup.cfg @@ -33,7 +33,9 @@ tkinter = doc = sphinx==6.2.1 nbsphinx - sphinx_rtd_theme + furo + sphinx_inline_tabs + sphinx_copybutton test = nox