Module clingox.program

This module provides functions to work with ground programs.

This includes constructing a ground representation using an observer, pretty printing the ground representation, and adding ground program to control objects via the backend.

Example

The following example shows how to:

• use the ProgramObserver to construct a Program, and
• add it to another Control object.

>>> from clingo.control import Control
>>> from clingox.program import Program, ProgramObserver, Remapping
>>>
>>> prg = Program()
>>> ctl_a = Control()
>>> ctl_a.register_observer(ProgramObserver(prg))
>>>
>>> ctl_a.add('base', [], 'a. {b}. c :- b.')
>>> ctl_a.ground([('base', [])])
>>> print(prg)
a.
__x1.
c :- b.
{b}.
>>>
>>> ctl_b = Control(['0'])
>>> with ctl_b.backend() as backend:
...     mapping = Remapping(backend, prg.output_atoms, prg.facts)
...     prg.add_to_backend(backend, mapping)
...
>>> ctl_b.solve(on_model=print)
a
b c a

Functions

def add_to_backend(stm,
backend: Backend)

Expand source code

@singledispatch
def add_to_backend(stm, backend: Backend):
    """
    Add statements to the backend using the provided mapping to map literals.

    Parameters
    ----------
    stm
        The statement to add to the backend.
    backend
        The backend.
    """
    # pylint: disable=unused-argument
    assert False, "unexpected type"

Add statements to the backend using the provided mapping to map literals.

Parameters

stm

The statement to add to the backend.

backend

The backend.

def pretty_str(stm,
output_atoms: Mapping[int, Symbol]) ‑> str

Expand source code

@singledispatch
def pretty_str(stm, output_atoms: OutputTable) -> str:
    """
    Pretty print statements.

    Parameters
    ----------
    stm
        The statement to convert to a string.
    output_atoms
        A mapping from program atoms to symbols.

    Returns
    -------
    The string representation of the statement.
    """
    # pylint: disable=unused-argument
    assert False, "unexpected type"

Pretty print statements.

Parameters

stm

The statement to convert to a string.

output_atoms

A mapping from program atoms to symbols.

Returns

The string representation of the statement.

def remap(stm, mapping: Callable[[int], int])

Expand source code

@singledispatch
def remap(stm, mapping: AtomMap):
    """
    Remap literals in the given statement with the provided mapping.

    Parameters
    ----------
    stm
        The statement to remap.
    mapping
        The mapping function to remap literals.

    Returns
    -------
    The updated statement.

    See Also
    --------
    Remapping
    """
    # pylint: disable=unused-argument
    assert False, "unexpected type"

Remap literals in the given statement with the provided mapping.

Parameters

stm

The statement to remap.

mapping

The mapping function to remap literals.

Returns

The updated statement.

See Also

Remapping

Classes

class Edge (u: int, v: int, condition: Sequence[int])

Expand source code

class Edge(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    u: int
    v: int
    condition: Sequence[Literal]

Ground representation of a heuristic statement.

Ancestors

• builtins.tuple

Instance variables

var condition : Sequence[int]

Expand source code

class Edge(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    u: int
    v: int
    condition: Sequence[Literal]

Alias for field number 2

var u : int

Expand source code

class Edge(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    u: int
    v: int
    condition: Sequence[Literal]

Alias for field number 0

var v : int

Expand source code

class Edge(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    u: int
    v: int
    condition: Sequence[Literal]

Alias for field number 1

class External (atom: int,
value: TruthValue)

Expand source code

class External(NamedTuple):
    """
    Ground representation of external atoms.
    """

    atom: Atom
    value: TruthValue

Ground representation of external atoms.

Ancestors

• builtins.tuple

Instance variables

var atom : int

Expand source code

class External(NamedTuple):
    """
    Ground representation of external atoms.
    """

    atom: Atom
    value: TruthValue

Alias for field number 0

var value : TruthValue

Expand source code

class External(NamedTuple):
    """
    Ground representation of external atoms.
    """

    atom: Atom
    value: TruthValue

Alias for field number 1

class Fact (symbol: Symbol)

Expand source code

class Fact(NamedTuple):
    """
    Ground representation of a fact.
    """

    symbol: Symbol

Ground representation of a fact.

Ancestors

• builtins.tuple

Instance variables

var symbol : Symbol

Expand source code

class Fact(NamedTuple):
    """
    Ground representation of a fact.
    """

    symbol: Symbol

Alias for field number 0

class Heuristic (atom: int,
type_: HeuristicType,
bias: int,
priority: int,
condition: Sequence[int])

Expand source code

class Heuristic(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    atom: Atom
    type_: HeuristicType
    bias: Weight
    priority: Weight
    condition: Sequence[Literal]

Ground representation of a heuristic statement.

Ancestors

• builtins.tuple

Instance variables

var atom : int

Expand source code

class Heuristic(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    atom: Atom
    type_: HeuristicType
    bias: Weight
    priority: Weight
    condition: Sequence[Literal]

Alias for field number 0

var bias : int

Expand source code

class Heuristic(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    atom: Atom
    type_: HeuristicType
    bias: Weight
    priority: Weight
    condition: Sequence[Literal]

Alias for field number 2

var condition : Sequence[int]

Expand source code

class Heuristic(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    atom: Atom
    type_: HeuristicType
    bias: Weight
    priority: Weight
    condition: Sequence[Literal]

Alias for field number 4

var priority : int

Expand source code

class Heuristic(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    atom: Atom
    type_: HeuristicType
    bias: Weight
    priority: Weight
    condition: Sequence[Literal]

Alias for field number 3

var type_ : HeuristicType

Expand source code

class Heuristic(NamedTuple):
    """
    Ground representation of a heuristic statement.
    """

    atom: Atom
    type_: HeuristicType
    bias: Weight
    priority: Weight
    condition: Sequence[Literal]

Alias for field number 1

class Minimize (priority: int, literals: Sequence[Tuple[int, int]])

Expand source code

class Minimize(NamedTuple):
    """
    Ground representation of a minimize statement.
    """

    priority: Weight
    literals: Sequence[Tuple[Literal, Weight]]

Ground representation of a minimize statement.

Ancestors

• builtins.tuple

Instance variables

var literals : Sequence[Tuple[int, int]]

Expand source code

class Minimize(NamedTuple):
    """
    Ground representation of a minimize statement.
    """

    priority: Weight
    literals: Sequence[Tuple[Literal, Weight]]

Alias for field number 1

var priority : int

Expand source code

class Minimize(NamedTuple):
    """
    Ground representation of a minimize statement.
    """

    priority: Weight
    literals: Sequence[Tuple[Literal, Weight]]

Alias for field number 0

class Program (output_atoms: MutableMapping[int, Symbol] = <factory>,
shows: List[Show] = <factory>,
facts: List[Fact] = <factory>,
rules: List[Rule] = <factory>,
weight_rules: List[WeightRule] = <factory>,
heuristics: List[Heuristic] = <factory>,
edges: List[Edge] = <factory>,
minimizes: List[Minimize] = <factory>,
externals: List[External] = <factory>,
projects: List[Project] | None = None,
assumptions: List[int] = <factory>)

Expand source code

@dataclass
class Program:  # pylint: disable=too-many-instance-attributes
    """
    Ground program representation.

    Although inefficient, the string representation of this program is parsable
    by clingo.
    """

    output_atoms: MutableMapping[Atom, Symbol] = field(default_factory=dict)
    """
    A mapping from program atoms to symbols.
    """
    shows: List[Show] = field(default_factory=list)
    """
    A list of show statements.
    """
    facts: List[Fact] = field(default_factory=list)
    """
    A list of facts.
    """
    rules: List[Rule] = field(default_factory=list)
    """
    A list of rules.
    """
    weight_rules: List[WeightRule] = field(default_factory=list)
    """
    A list of weight rules.
    """
    heuristics: List[Heuristic] = field(default_factory=list)
    """
    A list of heuristic statements.
    """
    edges: List[Edge] = field(default_factory=list)
    """
    A list of edge statements.
    """
    minimizes: List[Minimize] = field(default_factory=list)
    """
    A list of minimize statements.
    """
    externals: List[External] = field(default_factory=list)
    """
    A list of external statements.
    """
    projects: Optional[List[Project]] = None
    """
    A list of project statements.
    """
    assumptions: List[Literal] = field(default_factory=list)
    """
    A list of assumptions in form of program literals.
    """

    def _pretty_stms(self, arg: Iterable[Statement], sort: bool) -> Iterable[str]:
        if sort:
            arg = sorted(arg)
        return (pretty_str(x, self.output_atoms) for x in arg)

    def _pretty_assumptions(self, sort: bool) -> Iterable[str]:
        if not self.assumptions:
            return []
        arg = sorted(self.assumptions) if sort else self.assumptions
        assumptions = (_pretty_str_lit(lit, self.output_atoms) for lit in arg)
        return [f'% assumptions: {", ".join(assumptions)}']

    def _pretty_projects(self, sort: bool) -> Iterable[str]:
        if self.projects is None:
            return []
        # This is to inform that there is an empty projection statement.
        # It might be worth to allow writing just #project.
        if not self.projects:
            return ["#project x: #false."]
        arg = sorted(self.projects) if sort else self.projects
        return (pretty_str(project, self.output_atoms) for project in arg)

    def sort(self) -> "Program":
        """
        Sort the statements in the program inplace.

        Returns
        -------
        A reference to self.
        """
        self.shows.sort()
        self.facts.sort()
        self.rules.sort()
        self.weight_rules.sort()
        self.heuristics.sort()
        self.edges.sort()
        self.minimizes.sort()
        self.externals.sort()
        if self.projects is not None:
            self.projects.sort()
        self.assumptions.sort()

        return self

    def remap(self, mapping: AtomMap) -> "Program":
        """
        Remap the literals in the program inplace.

        Parameters
        ----------
        mapping
            A function to remap program atoms.

        Returns
        -------
        A reference to self.

        See Also
        --------
        remap
        """
        _remap_stms(self.shows, mapping)
        _remap_stms(self.facts, mapping)
        _remap_stms(self.rules, mapping)
        _remap_stms(self.weight_rules, mapping)
        _remap_stms(self.heuristics, mapping)
        _remap_stms(self.edges, mapping)
        _remap_stms(self.minimizes, mapping)
        _remap_stms(self.externals, mapping)
        if self.projects is not None:
            _remap_stms(self.projects, mapping)
        for i, lit in enumerate(self.assumptions):
            self.assumptions[i] = _remap_lit(lit, mapping)
        self.output_atoms = {
            mapping(lit): sym for lit, sym in self.output_atoms.items()
        }

        return self

    def add_to_backend(
        self, backend: Backend, mapping: Optional[AtomMap] = None
    ) -> "Program":
        """
        Add the program to the given backend with an optional mapping.

        Note that the output table cannot be added to the backend for technical
        reasons. This has to be taken care of by the user. See for example the
        `Remapping` class, which provides functionality for this.

        Parameters
        ----------
        backend
            The backend.
        mapping
            A mapping function to remap literals.

        Returns
        -------
        A reference to self.

        See Also
        --------
        add_to_backend
        """

        _add_stms_to_backend(self.shows, backend, mapping)
        _add_stms_to_backend(self.facts, backend, mapping)
        _add_stms_to_backend(self.rules, backend, mapping)
        _add_stms_to_backend(self.weight_rules, backend, mapping)
        _add_stms_to_backend(self.heuristics, backend, mapping)
        _add_stms_to_backend(self.edges, backend, mapping)
        _add_stms_to_backend(self.minimizes, backend, mapping)
        _add_stms_to_backend(self.externals, backend, mapping)
        if self.projects is not None:
            if self.projects:
                _add_stms_to_backend(self.projects, backend, mapping)
            else:
                backend.add_project([])

        backend.add_assume(
            [_remap_lit(lit, mapping) if mapping else lit for lit in self.assumptions]
        )

        return self

    def pretty_str(self, sort: bool = True) -> str:
        """
        Return a readable string represenation of the program.

        Parameters
        ----------
        sort
            Whether to sort the statements in the program befor printing.

        Returns
        -------
        The string representation of the program.
        """
        return "\n".join(
            chain(
                self._pretty_stms(self.shows, sort),
                self._pretty_stms(self.facts, sort),
                self._pretty_stms(self.rules, sort),
                self._pretty_stms(self.weight_rules, sort),
                self._pretty_stms(self.heuristics, sort),
                self._pretty_stms(self.edges, sort),
                self._pretty_stms(self.minimizes, sort),
                self._pretty_stms(self.externals, sort),
                self._pretty_projects(sort),
                self._pretty_assumptions(sort),
            )
        )

    def copy(self) -> "Program":
        """
        Return a shallow copy of the program copying all mutable state.

        Returns
        -------
        A shallow copy of the program.
        """
        return copy(self)

    def __str__(self) -> str:
        """
        Return a readable string represenation of the program.
        """
        return self.pretty_str()

Ground program representation.

Although inefficient, the string representation of this program is parsable by clingo.

Instance variables

var assumptions : List[int]

A list of assumptions in form of program literals.

var edges : List[Edge]

A list of edge statements.

var externals : List[External]

A list of external statements.

var facts : List[Fact]

A list of facts.

var heuristics : List[Heuristic]

A list of heuristic statements.

var minimizes : List[Minimize]

A list of minimize statements.

var output_atoms : MutableMapping[int, Symbol]

A mapping from program atoms to symbols.

var projects : List[Project] | None

A list of project statements.

var rules : List[Rule]

A list of rules.

var shows : List[Show]

A list of show statements.

var weight_rules : List[WeightRule]

A list of weight rules.

Methods

def add_to_backend(self,
backend: Backend,
mapping: Callable[[int], int] | None = None) ‑> Program

Expand source code

def add_to_backend(
    self, backend: Backend, mapping: Optional[AtomMap] = None
) -> "Program":
    """
    Add the program to the given backend with an optional mapping.

    Note that the output table cannot be added to the backend for technical
    reasons. This has to be taken care of by the user. See for example the
    `Remapping` class, which provides functionality for this.

    Parameters
    ----------
    backend
        The backend.
    mapping
        A mapping function to remap literals.

    Returns
    -------
    A reference to self.

    See Also
    --------
    add_to_backend
    """

    _add_stms_to_backend(self.shows, backend, mapping)
    _add_stms_to_backend(self.facts, backend, mapping)
    _add_stms_to_backend(self.rules, backend, mapping)
    _add_stms_to_backend(self.weight_rules, backend, mapping)
    _add_stms_to_backend(self.heuristics, backend, mapping)
    _add_stms_to_backend(self.edges, backend, mapping)
    _add_stms_to_backend(self.minimizes, backend, mapping)
    _add_stms_to_backend(self.externals, backend, mapping)
    if self.projects is not None:
        if self.projects:
            _add_stms_to_backend(self.projects, backend, mapping)
        else:
            backend.add_project([])

    backend.add_assume(
        [_remap_lit(lit, mapping) if mapping else lit for lit in self.assumptions]
    )

    return self

Add the program to the given backend with an optional mapping.

Note that the output table cannot be added to the backend for technical reasons. This has to be taken care of by the user. See for example the Remapping class, which provides functionality for this.

Parameters

backend

The backend.

mapping

A mapping function to remap literals.

Returns

A reference to self.

See Also

add_to_backend()

def copy(self) ‑> Program

Expand source code

def copy(self) -> "Program":
    """
    Return a shallow copy of the program copying all mutable state.

    Returns
    -------
    A shallow copy of the program.
    """
    return copy(self)

Return a shallow copy of the program copying all mutable state.

Returns

A shallow copy of the program.

def pretty_str(self, sort: bool = True) ‑> str

Expand source code

def pretty_str(self, sort: bool = True) -> str:
    """
    Return a readable string represenation of the program.

    Parameters
    ----------
    sort
        Whether to sort the statements in the program befor printing.

    Returns
    -------
    The string representation of the program.
    """
    return "\n".join(
        chain(
            self._pretty_stms(self.shows, sort),
            self._pretty_stms(self.facts, sort),
            self._pretty_stms(self.rules, sort),
            self._pretty_stms(self.weight_rules, sort),
            self._pretty_stms(self.heuristics, sort),
            self._pretty_stms(self.edges, sort),
            self._pretty_stms(self.minimizes, sort),
            self._pretty_stms(self.externals, sort),
            self._pretty_projects(sort),
            self._pretty_assumptions(sort),
        )
    )

Return a readable string represenation of the program.

Parameters

sort

Whether to sort the statements in the program befor printing.

Returns

The string representation of the program.

def remap(self, mapping: Callable[[int], int]) ‑> Program

Expand source code

def remap(self, mapping: AtomMap) -> "Program":
    """
    Remap the literals in the program inplace.

    Parameters
    ----------
    mapping
        A function to remap program atoms.

    Returns
    -------
    A reference to self.

    See Also
    --------
    remap
    """
    _remap_stms(self.shows, mapping)
    _remap_stms(self.facts, mapping)
    _remap_stms(self.rules, mapping)
    _remap_stms(self.weight_rules, mapping)
    _remap_stms(self.heuristics, mapping)
    _remap_stms(self.edges, mapping)
    _remap_stms(self.minimizes, mapping)
    _remap_stms(self.externals, mapping)
    if self.projects is not None:
        _remap_stms(self.projects, mapping)
    for i, lit in enumerate(self.assumptions):
        self.assumptions[i] = _remap_lit(lit, mapping)
    self.output_atoms = {
        mapping(lit): sym for lit, sym in self.output_atoms.items()
    }

    return self

Remap the literals in the program inplace.

Parameters

mapping

A function to remap program atoms.

Returns

A reference to self.

See Also

remap()

def sort(self) ‑> Program

Expand source code

def sort(self) -> "Program":
    """
    Sort the statements in the program inplace.

    Returns
    -------
    A reference to self.
    """
    self.shows.sort()
    self.facts.sort()
    self.rules.sort()
    self.weight_rules.sort()
    self.heuristics.sort()
    self.edges.sort()
    self.minimizes.sort()
    self.externals.sort()
    if self.projects is not None:
        self.projects.sort()
    self.assumptions.sort()

    return self

Sort the statements in the program inplace.

Returns

A reference to self.

class ProgramObserver (program: Program)

Expand source code

class ProgramObserver(Observer):
    """
    Program observer to build a ground program representation while grounding.

    This class explicitly ignores theory atoms because they already have a
    ground representation.

    Parameters
    ----------
    program
        The program to add statements to.
    """

    _program: Program

    def __init__(self, program: Program):
        self._program = program

    def begin_step(self) -> None:
        """
        Resets the assumptions.
        """
        self._program.assumptions.clear()

    def output_atom(self, symbol: Symbol, atom: Atom) -> None:
        """
        Add the given atom to the list of facts or output table.
        """
        if atom != 0:
            self._program.output_atoms[atom] = symbol
        else:
            self._program.facts.append(Fact(symbol))

    def output_term(self, symbol: Symbol, condition: Sequence[Literal]) -> None:
        """
        Add a term to the output table.
        """
        self._program.shows.append(Show(symbol, condition))

    def rule(self, choice: bool, head: Sequence[Atom], body: Sequence[Literal]) -> None:
        """
        Add a rule to the ground representation.

        Parameters
        ----------
        choice
            Determines if the head is a choice or a disjunction.
        head
            List of program atoms forming the rule head.
        body
            List of program literals forming the rule body.
        """
        self._program.rules.append(Rule(choice, head, body))

    def weight_rule(
        self,
        choice: bool,
        head: Sequence[Atom],
        lower_bound: Weight,
        body: Sequence[Tuple[Literal, Weight]],
    ) -> None:
        """
        Add a weight rule to the ground representation.

        Parameters
        ----------
        choice
            Determines if the head is a choice or a disjunction.
        head
            List of program atoms forming the head of the rule.
        lower_bound
            The lower bound of the weight constraint in the rule body.
        body
            List of weighted literals (pairs of literal and weight) forming the
            elements of the weight constraint.
        """
        self._program.weight_rules.append(WeightRule(choice, head, lower_bound, body))

    def project(self, atoms: Sequence[Atom]) -> None:
        """
        Add a project statement to the ground representation.

        Parameters
        ----------
        atoms
            The program atoms to project on.
        """
        if self._program.projects is None:
            self._program.projects = []
        self._program.projects.extend(Project(atom) for atom in atoms)

    def external(self, atom: Atom, value: TruthValue) -> None:
        """
        Add an external statement to the ground representation.

        Parameters
        ----------
        atom
            The external atom in form of a program literal.
        value
            The truth value of the external statement.
        """
        self._program.externals.append(External(atom, value))

    def assume(self, literals: Sequence[Literal]) -> None:
        """
        Extend the program with the given assumptions.

        Parameters
        ----------
        literals
            The program literals to assume (positive literals are true and
            negative literals false for the next solve call).
        """
        self._program.assumptions.extend(literals)

    def minimize(
        self, priority: Weight, literals: Sequence[Tuple[Literal, Weight]]
    ) -> None:
        """
        Add a minimize statement to the ground representation.

        Parameters
        ----------
        priority
            The priority of the directive.
        literals
            List of weighted literals whose sum to minimize (pairs of literal
            and weight).
        """
        self._program.minimizes.append(Minimize(priority, literals))

    def acyc_edge(self, node_u: int, node_v: int, condition: Sequence[Literal]) -> None:
        """
        Add an edge statement to the gronud representation.

        Parameters
        ----------
        node_u
            The start vertex of the edge (in form of an integer).
        node_v
            Тhe end vertex of the edge (in form of an integer).
        condition
            The list of program literals forming th condition under which to
            add the edge.
        """
        self._program.edges.append(Edge(node_u, node_v, condition))

    def heuristic(
        self,
        atom: Atom,
        type_: HeuristicType,
        bias: Weight,
        priority: Weight,
        condition: Sequence[Literal],
    ) -> None:
        """
        Add heurisitic statement to the gronud representation.

        Parameters
        ----------
        atom
            The program atom heuristically modified.
        type_
            The type of the modification.
        bias
            A signed integer.
        priority
            An unsigned integer.
        condition
            List of program literals.
        """
        self._program.heuristics.append(
            Heuristic(atom, type_, bias, priority, condition)
        )

Program observer to build a ground program representation while grounding.

This class explicitly ignores theory atoms because they already have a ground representation.

Parameters

program

The program to add statements to.

Ancestors

• Observer

Methods

def acyc_edge(self, node_u: int, node_v: int, condition: Sequence[int]) ‑> None

Expand source code

def acyc_edge(self, node_u: int, node_v: int, condition: Sequence[Literal]) -> None:
    """
    Add an edge statement to the gronud representation.

    Parameters
    ----------
    node_u
        The start vertex of the edge (in form of an integer).
    node_v
        Тhe end vertex of the edge (in form of an integer).
    condition
        The list of program literals forming th condition under which to
        add the edge.
    """
    self._program.edges.append(Edge(node_u, node_v, condition))

Add an edge statement to the gronud representation.

Parameters

node_u

The start vertex of the edge (in form of an integer).

node_v

Тhe end vertex of the edge (in form of an integer).

condition

The list of program literals forming th condition under which to add the edge.

def assume(self, literals: Sequence[int]) ‑> None

Expand source code

def assume(self, literals: Sequence[Literal]) -> None:
    """
    Extend the program with the given assumptions.

    Parameters
    ----------
    literals
        The program literals to assume (positive literals are true and
        negative literals false for the next solve call).
    """
    self._program.assumptions.extend(literals)

Extend the program with the given assumptions.

Parameters

literals

The program literals to assume (positive literals are true and negative literals false for the next solve call).

def begin_step(self) ‑> None

Expand source code

def begin_step(self) -> None:
    """
    Resets the assumptions.
    """
    self._program.assumptions.clear()

Resets the assumptions.

def external(self,
atom: int,
value: TruthValue) ‑> None

Expand source code

def external(self, atom: Atom, value: TruthValue) -> None:
    """
    Add an external statement to the ground representation.

    Parameters
    ----------
    atom
        The external atom in form of a program literal.
    value
        The truth value of the external statement.
    """
    self._program.externals.append(External(atom, value))

Add an external statement to the ground representation.

Parameters

atom

The external atom in form of a program literal.

value

The truth value of the external statement.

def heuristic(self,
atom: int,
type_: HeuristicType,
bias: int,
priority: int,
condition: Sequence[int]) ‑> None

Expand source code

def heuristic(
    self,
    atom: Atom,
    type_: HeuristicType,
    bias: Weight,
    priority: Weight,
    condition: Sequence[Literal],
) -> None:
    """
    Add heurisitic statement to the gronud representation.

    Parameters
    ----------
    atom
        The program atom heuristically modified.
    type_
        The type of the modification.
    bias
        A signed integer.
    priority
        An unsigned integer.
    condition
        List of program literals.
    """
    self._program.heuristics.append(
        Heuristic(atom, type_, bias, priority, condition)
    )

Add heurisitic statement to the gronud representation.

Parameters

atom

The program atom heuristically modified.

type_

The type of the modification.

bias

A signed integer.

priority

An unsigned integer.

condition

List of program literals.

def minimize(self, priority: int, literals: Sequence[Tuple[int, int]]) ‑> None

Expand source code

def minimize(
    self, priority: Weight, literals: Sequence[Tuple[Literal, Weight]]
) -> None:
    """
    Add a minimize statement to the ground representation.

    Parameters
    ----------
    priority
        The priority of the directive.
    literals
        List of weighted literals whose sum to minimize (pairs of literal
        and weight).
    """
    self._program.minimizes.append(Minimize(priority, literals))

Add a minimize statement to the ground representation.

Parameters

priority

The priority of the directive.

literals

List of weighted literals whose sum to minimize (pairs of literal and weight).

def output_atom(self,
symbol: Symbol,
atom: int) ‑> None

Expand source code

def output_atom(self, symbol: Symbol, atom: Atom) -> None:
    """
    Add the given atom to the list of facts or output table.
    """
    if atom != 0:
        self._program.output_atoms[atom] = symbol
    else:
        self._program.facts.append(Fact(symbol))

Add the given atom to the list of facts or output table.

def output_term(self,
symbol: Symbol,
condition: Sequence[int]) ‑> None

Expand source code

def output_term(self, symbol: Symbol, condition: Sequence[Literal]) -> None:
    """
    Add a term to the output table.
    """
    self._program.shows.append(Show(symbol, condition))

Add a term to the output table.

def project(self, atoms: Sequence[int]) ‑> None

Expand source code

def project(self, atoms: Sequence[Atom]) -> None:
    """
    Add a project statement to the ground representation.

    Parameters
    ----------
    atoms
        The program atoms to project on.
    """
    if self._program.projects is None:
        self._program.projects = []
    self._program.projects.extend(Project(atom) for atom in atoms)

Add a project statement to the ground representation.

Parameters

atoms

The program atoms to project on.

def rule(self, choice: bool, head: Sequence[int], body: Sequence[int]) ‑> None

Expand source code

def rule(self, choice: bool, head: Sequence[Atom], body: Sequence[Literal]) -> None:
    """
    Add a rule to the ground representation.

    Parameters
    ----------
    choice
        Determines if the head is a choice or a disjunction.
    head
        List of program atoms forming the rule head.
    body
        List of program literals forming the rule body.
    """
    self._program.rules.append(Rule(choice, head, body))

Add a rule to the ground representation.

Parameters

choice

Determines if the head is a choice or a disjunction.

head

List of program atoms forming the rule head.

body

List of program literals forming the rule body.

def weight_rule(self,
choice: bool,
head: Sequence[int],
lower_bound: int,
body: Sequence[Tuple[int, int]]) ‑> None

Expand source code

def weight_rule(
    self,
    choice: bool,
    head: Sequence[Atom],
    lower_bound: Weight,
    body: Sequence[Tuple[Literal, Weight]],
) -> None:
    """
    Add a weight rule to the ground representation.

    Parameters
    ----------
    choice
        Determines if the head is a choice or a disjunction.
    head
        List of program atoms forming the head of the rule.
    lower_bound
        The lower bound of the weight constraint in the rule body.
    body
        List of weighted literals (pairs of literal and weight) forming the
        elements of the weight constraint.
    """
    self._program.weight_rules.append(WeightRule(choice, head, lower_bound, body))

Add a weight rule to the ground representation.

Parameters

choice

Determines if the head is a choice or a disjunction.

head

List of program atoms forming the head of the rule.

lower_bound

The lower bound of the weight constraint in the rule body.

body

List of weighted literals (pairs of literal and weight) forming the elements of the weight constraint.

Inherited members

• Observer:
  • end_step
  • init_program
  • theory_atom
  • theory_atom_with_guard
  • theory_element
  • theory_term_compound
  • theory_term_number
  • theory_term_string

class Project (atom: int)

Expand source code

class Project(NamedTuple):
    """
    Ground representation of project statements.
    """

    atom: Atom

Ground representation of project statements.

Ancestors

• builtins.tuple

Instance variables

var atom : int

Expand source code

class Project(NamedTuple):
    """
    Ground representation of project statements.
    """

    atom: Atom

Alias for field number 0

class Remapping (backend: Backend,
output_atoms: Mapping[int, Symbol],
facts: Iterable[Fact] = ())

Expand source code

class Remapping:
    """
    This class maps existing literals to fresh literals as created by the
    backend.

    Parameters
    ----------
    backend
        The backend used to introduce fresh atoms.
    output_atoms
        The output table to initialize the mapping with.
    facts
        A list of facts each of which will receive a fresh program atom.
    """

    _backend: Backend
    _map: MutableMapping[Atom, Atom]

    def __init__(
        self, backend: Backend, output_atoms: OutputTable, facts: Iterable[Fact] = ()
    ):
        self._backend = backend
        self._map = {}
        for atom, sym in output_atoms.items():
            assert atom not in self._map
            self._map[atom] = self._backend.add_atom(sym)
        for fact in facts:
            backend.add_rule([backend.add_atom(fact.symbol)])

    def __call__(self, atom: Atom) -> Atom:
        """
        Map the given program atom to the corresponding atom in the backend.

        If the literal was not mapped during initialization, a new literal is
        associated with it.

        Parameters
        ----------
        atom
            The atom to remap.

        Returns
        -------
        The remapped program atom.
        """
        if atom not in self._map:
            self._map[atom] = self._backend.add_atom()

        return self._map[atom]

This class maps existing literals to fresh literals as created by the backend.

Parameters

backend

The backend used to introduce fresh atoms.

output_atoms

The output table to initialize the mapping with.

facts

A list of facts each of which will receive a fresh program atom.

Methods

def __call__(self, atom: int) ‑> int

Expand source code

def __call__(self, atom: Atom) -> Atom:
    """
    Map the given program atom to the corresponding atom in the backend.

    If the literal was not mapped during initialization, a new literal is
    associated with it.

    Parameters
    ----------
    atom
        The atom to remap.

    Returns
    -------
    The remapped program atom.
    """
    if atom not in self._map:
        self._map[atom] = self._backend.add_atom()

    return self._map[atom]

Map the given program atom to the corresponding atom in the backend.

If the literal was not mapped during initialization, a new literal is associated with it.

Parameters

atom

The atom to remap.

Returns

The remapped program atom.

class Rule (choice: bool, head: Sequence[int], body: Sequence[int])

Expand source code

class Rule(NamedTuple):
    """
    Ground representation of disjunctive and choice rules.
    """

    choice: bool
    head: Sequence[Atom]
    body: Sequence[Literal]

Ground representation of disjunctive and choice rules.

Ancestors

• builtins.tuple

Instance variables

var body : Sequence[int]

Expand source code

class Rule(NamedTuple):
    """
    Ground representation of disjunctive and choice rules.
    """

    choice: bool
    head: Sequence[Atom]
    body: Sequence[Literal]

Alias for field number 2

var choice : bool

Expand source code

class Rule(NamedTuple):
    """
    Ground representation of disjunctive and choice rules.
    """

    choice: bool
    head: Sequence[Atom]
    body: Sequence[Literal]

Alias for field number 0

var head : Sequence[int]

Expand source code

class Rule(NamedTuple):
    """
    Ground representation of disjunctive and choice rules.
    """

    choice: bool
    head: Sequence[Atom]
    body: Sequence[Literal]

Alias for field number 1

class Show (symbol: Symbol,
condition: Sequence[int])

Expand source code

class Show(NamedTuple):
    """
    Ground representation of a show statements.
    """

    symbol: Symbol
    condition: Sequence[Literal]

Ground representation of a show statements.

Ancestors

• builtins.tuple

Instance variables

var condition : Sequence[int]

Expand source code

class Show(NamedTuple):
    """
    Ground representation of a show statements.
    """

    symbol: Symbol
    condition: Sequence[Literal]

Alias for field number 1

var symbol : Symbol

Expand source code

class Show(NamedTuple):
    """
    Ground representation of a show statements.
    """

    symbol: Symbol
    condition: Sequence[Literal]

Alias for field number 0

class WeightRule (choice: bool,
head: Sequence[int],
lower_bound: int,
body: Sequence[Tuple[int, int]])

Expand source code

class WeightRule(NamedTuple):
    """
    Ground representation of rules with a weight constraint in the body.
    """

    choice: bool
    head: Sequence[Atom]
    lower_bound: Weight
    body: Sequence[Tuple[Literal, Weight]]

Ground representation of rules with a weight constraint in the body.

Ancestors

• builtins.tuple

Instance variables

var body : Sequence[Tuple[int, int]]

Expand source code

class WeightRule(NamedTuple):
    """
    Ground representation of rules with a weight constraint in the body.
    """

    choice: bool
    head: Sequence[Atom]
    lower_bound: Weight
    body: Sequence[Tuple[Literal, Weight]]

Alias for field number 3

var choice : bool

Expand source code

class WeightRule(NamedTuple):
    """
    Ground representation of rules with a weight constraint in the body.
    """

    choice: bool
    head: Sequence[Atom]
    lower_bound: Weight
    body: Sequence[Tuple[Literal, Weight]]

Alias for field number 0

var head : Sequence[int]

Expand source code

class WeightRule(NamedTuple):
    """
    Ground representation of rules with a weight constraint in the body.
    """

    choice: bool
    head: Sequence[Atom]
    lower_bound: Weight
    body: Sequence[Tuple[Literal, Weight]]

Alias for field number 1

var lower_bound : int

Expand source code

class WeightRule(NamedTuple):
    """
    Ground representation of rules with a weight constraint in the body.
    """

    choice: bool
    head: Sequence[Atom]
    lower_bound: Weight
    body: Sequence[Tuple[Literal, Weight]]

Alias for field number 2