Merge pull request #31 from potassco/stephanzwicknagl/issue10

Stephanzwicknagl/issue10

README.md

@@ -1,11 +1,11 @@
 # viASP
 
-[![Build and Test](https://github.com/stephanzwicknagl/viasp/actions/workflows/build_and_test.yml/badge.svg?branch=main)](https://github.com/stephanzwicknagl/viasp/actions/workflows/build_and_test.yml) [![Documentation Status](https://readthedocs.org/projects/viasp/badge/?version=latest)](https://viasp.readthedocs.io/en/latest/?badge=latest)
+[![Build and Test](https://github.com/potassco/viasp/actions/workflows/build_and_test.yml/badge.svg?branch=main)](https://github.com/potassco/viasp/actions/workflows/build_and_test.yml) [![Documentation Status](https://readthedocs.org/projects/viasp/badge/?version=latest)](https://viasp.readthedocs.io/en/latest/?badge=latest)
 
-**viASP visualizes an interactive explanation of your ASP program and its stable models** 
+## viASP generates an interactive visualization of your ASP program and its stable models
 
 Try it out in Binder!
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/stephanzwicknagl/viasp/main?filepath=examples%2FIntroduction%20to%20viASP.ipynb)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/potassco/viasp/main?filepath=examples%2FIntroduction%20to%20viASP.ipynb)
 
 ![Example visualization](docs/img/header.png)
 
@@ -20,15 +20,28 @@ viASP allows you to explore the visualization in a variety of ways:
 * Add `#show` statements on the fly
 * Search models, signatures and rules.
 
-# Usage
+## Installation
 
-Check out the [documentation](https://viasp.readthedocs.io/en/latest/) to see how to use viASP.
+viASP is available on [PyPI](https://pypi.org/project/viasp/). You can install it with pip:
 
-### Examples
+```bash
+pip install viasp
+```
 
-An introduction to viASP's features is given in the [notebook](https://mybinder.org/v2/gh/stephanzwicknagl/viasp/main?filepath=examples%2FIntroduction%20to%20viASP.ipynb). The [examples folder](https://github.com/stephanzwicknagl/viasp/tree/main/examples) shows a variety of scripts that run viASP.
+## Usage
+
+To start a visualization from the command line, run:
+
+```bash
+viasp path/to/encoding.lp
+```
 
+Check out the [documentation](https://viasp.readthedocs.io/en/latest/) to see more on how to use viASP.
+
+## Examples
+
+An introduction to viASP's features is given in the [notebook](https://mybinder.org/v2/gh/stephanzwicknagl/viasp/main?filepath=examples%2FIntroduction%20to%20viASP.ipynb). The [examples folder](https://github.com/stephanzwicknagl/viasp/tree/main/examples) shows a variety of scripts that run viASP.
 
-# Contributing
+## Contributing
 
 See the [documentation page](https://viasp.readthedocs.io/en/latest/viasp/contributing.html#contributing) to see how to contribute.

backend/src/viasp/__main__.py

@@ -1,29 +1,18 @@
 import argparse
 import textwrap
 import webbrowser
+import importlib.metadata
 
 from viasp import Control
 from viasp.server import startup
 from viasp.shared.defaults import DEFAULT_BACKEND_HOST, DEFAULT_BACKEND_PORT, DEFAULT_FRONTEND_PORT, DEFAULT_BACKEND_PROTOCOL
 
+try:
+    VERSION = importlib.metadata.version("viasp")
+except importlib.metadata.PackageNotFoundError:
+    VERSION = '0.0.0'
 
-def backend():
-    from viasp.server.factory import create_app
-    parser = argparse.ArgumentParser(description='viasp backend')
-    parser.add_argument('--host', type=str, help='The host for the backend', default=DEFAULT_BACKEND_HOST)
-    parser.add_argument('-p', '--port', type=int, help='The port for the backend', default=DEFAULT_BACKEND_PORT)
-    app = create_app()
-    use_reloader = False
-    debug = False
-    args = parser.parse_args()
-    host = args.host
-    port = args.port
-    print(f"Starting viASP backend at {host}:{port}")
-    app.run(host=host, port=port, use_reloader=use_reloader, debug=debug)
-
-
-
-def start():
+def _get_parser():
     parser = argparse.ArgumentParser(prog='viasp', description=textwrap.dedent(r"""
            _           _____ _____  
           (_)   /\    / ____|  __ \ 
@@ -32,13 +21,17 @@ def start():
      \ V /| |/ ____ \ ____) | |     
       \_/ |_/_/    \_\_____/|_|     
                     
-    viASP is a package to generate responsive visualizations of ASP programs and their stable models. 
+    viASP is a package to generate interactive 
+    visualizations of ASP programs and 
+    their stable models. 
     """), formatter_class=argparse.RawTextHelpFormatter)
     parser.add_argument('paths', nargs='+', help='Runs viASP with the paths to programs to be loaded')
     parser.add_argument('-n', '--models', type=int, help='Compute at most <n> models (0 for all)', default=0)
     parser.add_argument('--host', type=str, help='The host for the backend and frontend', default=DEFAULT_BACKEND_HOST)
     parser.add_argument('-p', '--port', type=int, help='The port for the backend', default=DEFAULT_BACKEND_PORT)
     parser.add_argument('-f', '--frontend-port', type=int, help='The port for the frontend', default=DEFAULT_FRONTEND_PORT)
+    parser.add_argument('--version','-v', action='version',
+                    version=f'%(prog)s {VERSION}')
 
 
     clingraph_group = parser.add_argument_group('Clingraph', 'If included, a clingraph visualization will be made.')
@@ -53,6 +46,28 @@ def start():
 
     # TODO: transformer
 
+    return parser
+
+
+def backend():
+    from viasp.server.factory import create_app
+    parser = argparse.ArgumentParser(description='viasp backend')
+    parser.add_argument('--host', type=str, help='The host for the backend', default=DEFAULT_BACKEND_HOST)
+    parser.add_argument('-p', '--port', type=int, help='The port for the backend', default=DEFAULT_BACKEND_PORT)
+    app = create_app()
+    use_reloader = False
+    debug = False
+    args = parser.parse_args()
+    host = args.host
+    port = args.port
+    print(f"Starting viASP backend at {host}:{port}")
+    app.run(host=host, port=port, use_reloader=use_reloader, debug=debug)
+
+
+
+def start():
+    parser = _get_parser()
+
     args = parser.parse_args()
     models = args.models
     no_relaxer = args.no_relaxer

docs/index.rst

@@ -28,6 +28,7 @@ viASP allows you to explore the visualization in a variety of ways:
    :caption: Contents:
 
    viasp/installation
+   viasp/commandline
    viasp/usage
    viasp/api
    viasp/contributing

docs/viasp/commandline.rst

@@ -0,0 +1,97 @@
+==========================
+Command line functionality
+==========================
+
+viASP provides command line functionality to generate graphs from files. The graphs can then be inspected in the browser.
+
+
+To use viASP from the command line, simply run
+
+.. code-block:: bash
+
+    $ viasp encoding.lp
+
+You can now inspect the visualization at http://localhost:8050/. To stop the server, press ``CTRL+C``.
+
+
+The command line usage is described below. Additionally, all options can be found by running
+
+.. code-block:: bash
+
+    $ viasp --help
+
+
+Loading Programs
+================
+
+To load a program, pass the path to the program file as an argument. For programs split into multiple files, all of them can be loaded at once.
+
+.. code-block:: bash
+
+    $ viasp sprinkler.lp encoding2.lp
+
+The output prints the stable models of the program and information about the viasp server and frontend url
+
+.. code-block:: bash
+    
+    Starting backend at http://localhost:5050
+    Answer:
+    rain wet    
+    Answer:
+    sprinkler wet
+    SAT
+    [INFO] (2023-12-01 12:38:44) Set models.
+    [INFO] (2023-12-01 12:38:44) Reconstructing in progress.
+    [INFO] (2023-12-01 12:38:44) Drawing in progress.
+    Dash is running on http://localhost:8050/
+
+    Press CTRL+C to quit
+
+
+To define how many models should be included at most, use the ``--models`` or ``-n`` option.
+
+.. code-block:: bash
+
+    $ viasp encoding.lp -n 3
+
+
+Clingraph
+=========
+
+viASP can include clingraph visualizations in the frontend. To do so, pass the path to a separte visualization program as an argument.
+
+.. code-block:: bash
+
+    $ viasp encoding.lp --viz_encoding viz_encoding.lp
+
+To pass additional arguments to clingraph, use the ``--engine`` and ``--graphviz_type`` options.
+
+.. code-block:: bash
+
+    $ viasp encoding.lp --viz_encoding viz_encoding.lp --engine clingraph --graphviz_type dot
+
+
+Relaxer
+=======
+
+By default, viASP supports the visualization of unsatisfiable programs using the relaxer. viASP transforms the integrity constraints of unsatisfiable programs into weak constraints and visualizes the resulting program. The resulting graph can be used to inspect the reason for unsatisfiability.
+
+By default, variables in the body of integrity constraints are collected in the heads of constraints. To turn off this behavior, use the ``--no-collect-variables`` option.
+
+To specify the head name of the weak constraint, use the ``--head_name`` option. By default, the head name is ``unsat``, but a different name should be specified, if the program already contains the predicate.
+
+.. code-block:: bash
+
+    $ viasp encoding.lp --head_name _unsat
+
+
+To turn off the relaxer, use the ``--no-relaxer`` or ``-r`` option.
+
+Other options
+=============
+
+To specify the port of the backend, use the ``--port`` or ``-p`` option.
+
+To specify the port of the frontend, use the ``--frontend-port`` or ``-f`` option.
+
+To specify the host of both frontend and backend, use the ``--host`` option.

docs/viasp/contributing.rst

@@ -30,8 +30,8 @@ Developing the frontend
 
 1. Move to frontend folder :code:`cd viasp/frontend`
 2. Run :code:`npm i` to install all needed dependencies
-3. Run :code:`npx webpack` to pack the javascript
-4. Run viASP with a clingo program :code:`viasp encoding.lp`
+3. Run :code:`npm run start` to continuously pack the javascript
+4. Run a modified viASP App to see changes on the frontend immediately :code:`python DevApp.py 0 encoding.lp`
 
 .. Note::
     The JavaScript and CSS files are located at ``/frontend/src/lib``. The frontend code needs to be packed before changes become visible to the webpage.

docs/viasp/installation.rst

@@ -7,20 +7,17 @@ Installing with pip
 
 The python viasp package can be found `here <https://pypi.org/project/viasp/>`_.
 
-.. warning:: 
-    The latest version is currently not available on PyPI. Please install from source.
-
 .. code-block:: bash
 
     $ pip install viasp
 
 .. warning:: 
-    To support the usage of clingraph in viASP, the user must first install `graphviz <https://www.graphviz.org/download/>`_  (version 2.50 or greater) manually.
+    To support the usage of clingraph in viASP, install `graphviz <https://www.graphviz.org/download/>`_  (version 2.50 or greater) manually.
 
 Installing from source
 ======================
 
-The project can currently only be installed from source. To do so, clone the repository at https://github.com/stephanzwicknagl/viasp and run the following commands in the root directory of the project:
+The project can also be installed from source. To do so, clone the repository at https://github.com/potassco/viasp and run the following commands in the root directory of the project:
 
 1. create a virtual environment
 
@@ -40,4 +37,4 @@ The project can currently only be installed from source. To do so, clone the rep
 
 .. code-block:: bash
 
-    $ pip install -q viasp viasp/backend viasp/frontend
+    $ pip install viasp viasp/backend viasp/frontend

docs/viasp/usage.rst

@@ -1,30 +1,14 @@
-=====
-Usage
-=====
-
-viASP consists of two parts, its frontend Dash component and the backend Flask server. Both need to be started and intialized on the local machine before each use.
-
-There are multiple ways of quickly starting viASP, which simplify the startup and initialization processes.
-
-
-Command-line functionality
-==========================
-
-.. warning::
-    this is currently a planned feature
-
-viASP can be used from the command line. Simply run
-
-.. code-block:: bash
-
-    $ viasp encoding.lp
-
-You can now inspect them using viASP at http://127.0.0.1:8050/.
-
+============
+Python Usage
+============
 
 Quickstart script
 =================
 
+viASP consists of two parts, its frontend Dash component and the backend Flask server. Both need to be started and intialized on the local machine before each use.
+
+There are multiple ways aside from the command line functionality to quickly start all parts of viASP while remaining in control of the program flow. The following example shows how to start viASP from a simple python script.
+
 Run the script at ``example/quickstart.py`` to start viASP with a given encoding.
 
 .. code-block:: bash

setup.cfg

@@ -15,8 +15,8 @@ classifiers =
 [options]
 python_requires = >=3.7
 install_requires =
-#     viasp-backend>=1.3.2
-#     viasp-dash>=1.1.6
+    viasp-backend>=2.0.0
+    viasp-dash>=2.0.0
 packages = find:
 package_dir =
     =.

setup.py

@@ -34,8 +34,8 @@ def run(self):
 
 # What packages are required for this module to be executed?
 REQUIRED = [
-    # 'viasp-backend',#>=1.3.2,
-    # 'viasp-dash',#>=1.1.6
+    'viasp-backend',
+    'viasp-dash',
     'jupyter-server-proxy',
     'clingraph',
     'graphviz',