API Documentation#

This module can be used to interact with the viasp backend.

It provides similar functions to viASP’s proxy Control class, but works independently of a clingo Control object program.

In addition to the proxy’s functions, this module provides functions to interact with it outside of a clingo program. Models can be marked directly from strings or files containing the corresponding facts.

load_program_file(path, **kwargs)[source]#

Load a (non-ground) program file into the viasp backend

Parameters

path (str or list) – path or list of paths to the program file

Kwargs:
viasp_backend_url (str) –

url of the viasp backend

_viasp_client (ClingoClient) –

a viasp client object

See also

load_program_string

load_program_string(program, **kwargs)[source]#

Load a (non-ground) program into the viasp backend

Parameters

program (str) – the program to load

Kwargs:
viasp_backend_url (str) –

url of the viasp backend

_viasp_client (ClingoClient) –

a viasp client object

See also

load_program_file

add_program_file(*args, **kwargs)[source]#

Add a (non-ground) program file to the viasp backend. This function provides two overloads, similar to clingo.control.Control.add.

def add(self, name: str, parameters: Sequence[str], path: str) -> None:
    ...

def add(self, path: str) -> None:
    return self.add("base", [], path)
Parameters

  • name (str) – The name of program block to add.

  • parameters (Sequence[str]) – The parameters of the program block to add.

  • path (str or list) – The path or list of paths to the non-ground program.

Kwargs:
viasp_backend_url (str) –

url of the viasp backend

_viasp_client (ClingoClient) –

a viasp client object

See also

add_program_string

add_program_string(*args, **kwargs)[source]#

Add a (non-ground) program to the viasp backend. This function provides two overloads, similar to clingo.control.Control.add.

def add(self, name: str, parameters: Sequence[str], program: str) -> None:
    ...

def add(self, program: str) -> None:
    return self.add("base", [], program)
Parameters

  • name (str) – The name of program block to add.

  • parameters (Sequence[str]) – The parameters of the program block to add.

  • program (str) – The non-ground program in string form.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

See also

add_program_file

mark_from_clingo_model(model, **kwargs)[source]#

Mark a model to be visualized. Models can be unmarked and cleared. The marked models are propagated to the backend when show is called.

Parameters

model (clingo.solving.Model or viasp.model.StableModel) – The model to mark.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

See also

unmark_from_clingo_model mark_from_string mark_from_file

mark_from_string(model, **kwargs)[source]#

Parse a string of ASP facts and mark them as a model.

Facts must be of a simple form. Rules that are NOT simple facts include: any rule with a body, a disjunctive fact, a choice rule, a theory atom, a literal with an external @-function reference, a literal that requires some mathematical calculation (eg., “p(1+1).”)

Models can be unmarked and cleared. The marked models are propagated to the backend when show is called.

Parameters

model (str) – The facts of the model to mark.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

Raises

InvalidSyntax if the string contains non-facts.

See also

mark_from_clingo_model mark_from_file unmark_from_string

mark_from_file(path, **kwargs)[source]#

Parse a file containing a string of ASP facts and mark them as a model.

Facts must be of a simple form. Rules that are NOT simple facts include: any rule with a body, a disjunctive fact, a choice rule, a theory atom, a literal with an external @-function reference, a literal that requires some mathematical calculation (eg., “p(1+1).”)

Models can be unmarked and cleared. The marked models are propagated to the backend when show is called.

Parameters

path (str or list) – The path or list of paths to the file containing the facts of the model to mark.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

Raises

InvalidSyntax if the string contains non-facts.

See also

mark_from_clingo_model mark_from_string unmark_from_file

unmark_from_clingo_model(model, **kwargs)[source]#

Unmark a model.

Parameters

model (clingo.solving.Model or viasp.model.StableModel) – The model to unmark.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

See also

mark_from_clingo_model unmark_from_string unmark_from_file

unmark_from_string(model, **kwargs)[source]#

Parse a string of ASP facts and unmark the corresponding model.

The string must be an exact match to the model.

Facts must be of a simple form. Rules that are NOT simple facts include: any rule with a body, a disjunctive fact, a choice rule, a theory atom, a literal with an external @-function reference, a literal that requires some mathematical calculation (eg., “p(1+1).”).

Changes to marked models are propagated to the backend when show is called.

Parameters

model (str) – The facts of the model to unmark.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

Raises

InvalidSyntax if the string contains non-facts.

See also

unmark_from_clingo_model unmark_from_file

unmark_from_file(path, **kwargs)[source]#

Parse a file containing a string of ASP facts and unmark the corresponding model.

The string must be an exact match to the model.

Facts must be of a simple form. Rules that are NOT simple facts include: any rule with a body, a disjunctive fact, a choice rule, a theory atom, a literal with an external @-function reference, a literal that requires some mathematical calculation (eg., “p(1+1).”).

Changes to marked models are propagated to the backend when show is called.

Parameters

path (str) – The path to the file containing the facts of the model to unmark.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

Raises

InvalidSyntax if the string contains non-facts.

See also

unmark_from_clingo_model unmark_from_string

clear(**kwargs)[source]#

Clear all marked models.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

show(**kwargs)[source]#

Propagate the marked models to the backend and Generate the graph.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

get_relaxed_program(*args, **kwargs)[source]#

Relax constraints in the marked models. Returns the relaxed program as a string.

Parameters

  • head_name (str, optional) – Name of head literal, defaults to “unsat”

  • collect_variables (bool, optional) – Collect variables from body as a tuple in the head literal, defaults to True

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

See also

relax_constraints

relax_constraints(*args, **kwargs)[source]#

Relax constraints in the loaded program. Returns a new viasp.Control object with the relaxed program loaded and stable models marked.

Parameters

  • head_name (str, optional) – Name of head literal. Defaults to “unsat”

  • collect_variables (bool, optional) – Collect variables from body as a tuple in the head literal. Defaults to True

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

See also

get_relaxed_program

clingraph(viz_encoding, engine='dot', graphviz_type='graph', **kwargs)[source]#

Generate the a clingraph from the marked models and the visualization encoding.

Parameters

  • viz_encoding (str) – The path to the visualization encoding.

  • engine (str) – The visualization engine. Defaults to “dot”.

  • graphviz_type (str) – The graph type. Defaults to “graph”.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

Note

See https://github.com/potassco/clingraph for more details.

register_transformer(transformer, imports='', path='', **kwargs)[source]#

Register a transformer to the backend. The program will be transformed in the backend before further processing is made.

Parameters

  • transformer (Transformer) – The transformer to register.

  • imports (str) – The imports usued by the transformer. (Can only be clingo imports and standard imports. String lines must be separated by newlines.)

  • path (str) – The path to the transformer.

Kwargs:

  • viasp_backend_url (str) – url of the viasp backend

  • _viasp_client (ClingoClient) – a viasp client object

Exceptions#

Exceptions

exception InvalidSyntax(*args)[source]#

Exception returned when the input syntax is not expected

exception InvalidSyntaxJSON(*args)[source]#

Exception returned when the input syntax is not expected

exception NoRelaxedModelsFoundException(message='No relaxed models were found.')[source]#

Exception raised when no relaxed models are found.