Module `clingo.configuration`

Functions and classes related to configuration.

Examples

The following example shows how to modify the configuration to enumerate all models:

>>> from clingo.control import Control
>>>
>>> ctl = Control()
>>> ctl.configuration.keys
['tester', 'solve', 'asp', 'solver', 'configuration', 'share',
 'learn_explicit', 'sat_prepro', 'stats', 'parse_ext', 'parse_maxsat']
>>> ctl.configuration.solve.keys
['solve_limit', 'parallel_mode', 'global_restarts', 'distribute',
 'integrate', 'enum_mode', 'project', 'models', 'opt_mode']
>>> ctl.configuration.solve.description("models")
'Compute at most %A models (0 for all)\n'
>>> ctl.configuration.solve.models = 0
>>> ctl.add("base", [], "1 {a; b}.")
>>> ctl.ground([("base", [])])
>>> print(ctl.solve(on_model=print))
b
a
a b
SAT

Expand source code

'''
Functions and classes related to configuration.

Examples
--------
The following example shows how to modify the configuration to enumerate all
models:

```python
>>> from clingo.control import Control
>>>
>>> ctl = Control()
>>> ctl.configuration.keys
['tester', 'solve', 'asp', 'solver', 'configuration', 'share',
 'learn_explicit', 'sat_prepro', 'stats', 'parse_ext', 'parse_maxsat']
>>> ctl.configuration.solve.keys
['solve_limit', 'parallel_mode', 'global_restarts', 'distribute',
 'integrate', 'enum_mode', 'project', 'models', 'opt_mode']
>>> ctl.configuration.solve.description("models")
'Compute at most %A models (0 for all)\\n'
>>> ctl.configuration.solve.models = 0
>>> ctl.add("base", [], "1 {a; b}.")
>>> ctl.ground([("base", [])])
>>> print(ctl.solve(on_model=print))
b
a
a b
SAT
```
'''

from typing import List, Optional, Union

from ._internal import _c_call, _ffi, _handle_error, _lib, _to_str

__all__ = [ 'Configuration' ]

class Configuration:
    '''
    Allows for changing the configuration of the underlying solver.

    Options are organized hierarchically. To change and inspect an option use:

        config.group.subgroup.option = "value"
        value = config.group.subgroup.option

    There are also arrays of option groups that can be accessed using integer
    indices:

        config.group.subgroup[0].option = "value1"
        config.group.subgroup[1].option = "value2"

    To list the subgroups of an option group, use the `Configuration.keys`
    member. Array option groups, like solver, can be iterated. Furthermore,
    there are meta options having key `configuration`. Assigning a meta option
    sets a number of related options.  To get further information about an
    option or option group, use `Configuration.description`.

    Notes
    -----
    The value of an option is always a string and any value assigned to an
    option is automatically converted into a string.

    See Also
    --------
    clingo.control.Control.configuration
    '''
    def __init__(self, rep, key):
        # Note: we have to bypass __setattr__ to avoid infinite recursion
        super().__setattr__("_rep", rep)
        super().__setattr__("_key", key)

    @property
    def _type(self) -> int:
        return _c_call('clingo_configuration_type_bitset_t', _lib.clingo_configuration_type, self._rep, self._key)

    @property
    def is_array(self) -> bool:
        '''
        This property is true if the configuration option is an array.
        '''
        return bool(self._type & _lib.clingo_configuration_type_array)

    def _get_subkey(self, name: str) -> Optional[int]:
        if self._type & _lib.clingo_configuration_type_map:
            if _c_call('bool', _lib.clingo_configuration_map_has_subkey, self._rep, self._key, name.encode()):
                return _c_call('clingo_id_t', _lib.clingo_configuration_map_at, self._rep, self._key, name.encode())
        return None

    def __len__(self):
        if self._type & _lib.clingo_configuration_type_array:
            return _c_call('size_t', _lib.clingo_configuration_array_size, self._rep, self._key)
        return 0

    def __getitem__(self, idx: int) -> 'Configuration':
        if idx < 0 or idx >= len(self):
            raise IndexError("invalid index")

        key = _c_call('clingo_id_t', _lib.clingo_configuration_array_at, self._rep, self._key, idx)
        return Configuration(self._rep, key)

    def __getattr__(self, name: str) -> Union[None, str, 'Configuration']:
        key = self._get_subkey(name)
        if key is None:
            raise AttributeError(f'no attribute: {name}')

        type_ = _c_call('clingo_configuration_type_bitset_t', _lib.clingo_configuration_type, self._rep, key)

        if type_ & _lib.clingo_configuration_type_value:
            if not _c_call('bool', _lib.clingo_configuration_value_is_assigned, self._rep, key):
                return None

            size = _c_call('size_t', _lib.clingo_configuration_value_get_size, self._rep, key)

            c_val = _ffi.new('char[]', size)
            _handle_error(_lib.clingo_configuration_value_get(self._rep, key, c_val, size))
            return _to_str(c_val)

        return Configuration(self._rep, key)

    def __setattr__(self, name: str, val) -> None:
        key = self._get_subkey(name)
        if key is None:
            super().__setattr__(name, val)
        else:
            _handle_error(_lib.clingo_configuration_value_set(self._rep, key, str(val).encode()))

    def description(self, name: str) -> str:
        '''
        Get a description for an option or option group.

        Parameters
        ----------
        name
            The name of the option.
        '''
        key = self._get_subkey(name)
        if key is None:
            raise RuntimeError(f'unknown option {name}')
        return _to_str(_c_call('char*', _lib.clingo_configuration_description, self._rep, key))

    @property
    def keys(self) -> Optional[List[str]]:
        '''
        The list of names of sub-option groups or options.

        The list is `None` if the current object is not an option group.
        '''
        ret = None
        if self._type & _lib.clingo_configuration_type_map:
            ret = []
            for i in range(_c_call('size_t', _lib.clingo_configuration_map_size, self._rep, self._key)):
                name = _c_call('char*', _lib.clingo_configuration_map_subkey_name, self._rep, self._key, i)
                ret.append(_to_str(name))
        return ret

Classes

class Configuration (rep, key)

Allows for changing the configuration of the underlying solver.

Options are organized hierarchically. To change and inspect an option use:

config.group.subgroup.option = "value"
value = config.group.subgroup.option

There are also arrays of option groups that can be accessed using integer indices:

config.group.subgroup[0].option = "value1"
config.group.subgroup[1].option = "value2"

To list the subgroups of an option group, use the Configuration.keys member. Array option groups, like solver, can be iterated. Furthermore, there are meta options having key configuration. Assigning a meta option sets a number of related options. To get further information about an option or option group, use Configuration.description().

Notes

The value of an option is always a string and any value assigned to an option is automatically converted into a string.

class Configuration:
    '''
    Allows for changing the configuration of the underlying solver.

    Options are organized hierarchically. To change and inspect an option use:

        config.group.subgroup.option = "value"
        value = config.group.subgroup.option

    There are also arrays of option groups that can be accessed using integer
    indices:

        config.group.subgroup[0].option = "value1"
        config.group.subgroup[1].option = "value2"

    To list the subgroups of an option group, use the `Configuration.keys`
    member. Array option groups, like solver, can be iterated. Furthermore,
    there are meta options having key `configuration`. Assigning a meta option
    sets a number of related options.  To get further information about an
    option or option group, use `Configuration.description`.

    Notes
    -----
    The value of an option is always a string and any value assigned to an
    option is automatically converted into a string.

    See Also
    --------
    clingo.control.Control.configuration
    '''
    def __init__(self, rep, key):
        # Note: we have to bypass __setattr__ to avoid infinite recursion
        super().__setattr__("_rep", rep)
        super().__setattr__("_key", key)

    @property
    def _type(self) -> int:
        return _c_call('clingo_configuration_type_bitset_t', _lib.clingo_configuration_type, self._rep, self._key)

    @property
    def is_array(self) -> bool:
        '''
        This property is true if the configuration option is an array.
        '''
        return bool(self._type & _lib.clingo_configuration_type_array)

    def _get_subkey(self, name: str) -> Optional[int]:
        if self._type & _lib.clingo_configuration_type_map:
            if _c_call('bool', _lib.clingo_configuration_map_has_subkey, self._rep, self._key, name.encode()):
                return _c_call('clingo_id_t', _lib.clingo_configuration_map_at, self._rep, self._key, name.encode())
        return None

    def __len__(self):
        if self._type & _lib.clingo_configuration_type_array:
            return _c_call('size_t', _lib.clingo_configuration_array_size, self._rep, self._key)
        return 0

    def __getitem__(self, idx: int) -> 'Configuration':
        if idx < 0 or idx >= len(self):
            raise IndexError("invalid index")

        key = _c_call('clingo_id_t', _lib.clingo_configuration_array_at, self._rep, self._key, idx)
        return Configuration(self._rep, key)

    def __getattr__(self, name: str) -> Union[None, str, 'Configuration']:
        key = self._get_subkey(name)
        if key is None:
            raise AttributeError(f'no attribute: {name}')

        type_ = _c_call('clingo_configuration_type_bitset_t', _lib.clingo_configuration_type, self._rep, key)

        if type_ & _lib.clingo_configuration_type_value:
            if not _c_call('bool', _lib.clingo_configuration_value_is_assigned, self._rep, key):
                return None

            size = _c_call('size_t', _lib.clingo_configuration_value_get_size, self._rep, key)

            c_val = _ffi.new('char[]', size)
            _handle_error(_lib.clingo_configuration_value_get(self._rep, key, c_val, size))
            return _to_str(c_val)

        return Configuration(self._rep, key)

    def __setattr__(self, name: str, val) -> None:
        key = self._get_subkey(name)
        if key is None:
            super().__setattr__(name, val)
        else:
            _handle_error(_lib.clingo_configuration_value_set(self._rep, key, str(val).encode()))

    def description(self, name: str) -> str:
        '''
        Get a description for an option or option group.

        Parameters
        ----------
        name
            The name of the option.
        '''
        key = self._get_subkey(name)
        if key is None:
            raise RuntimeError(f'unknown option {name}')
        return _to_str(_c_call('char*', _lib.clingo_configuration_description, self._rep, key))

    @property
    def keys(self) -> Optional[List[str]]:
        '''
        The list of names of sub-option groups or options.

        The list is `None` if the current object is not an option group.
        '''
        ret = None
        if self._type & _lib.clingo_configuration_type_map:
            ret = []
            for i in range(_c_call('size_t', _lib.clingo_configuration_map_size, self._rep, self._key)):
                name = _c_call('char*', _lib.clingo_configuration_map_subkey_name, self._rep, self._key, i)
                ret.append(_to_str(name))
        return ret

Instance variables

var is_array : bool

This property is true if the configuration option is an array.

Expand source code

@property
def is_array(self) -> bool:
    '''
    This property is true if the configuration option is an array.
    '''
    return bool(self._type & _lib.clingo_configuration_type_array)

var keys : Optional[List[str]]

The list of names of sub-option groups or options.

The list is None if the current object is not an option group.

Expand source code

@property
def keys(self) -> Optional[List[str]]:
    '''
    The list of names of sub-option groups or options.

    The list is `None` if the current object is not an option group.
    '''
    ret = None
    if self._type & _lib.clingo_configuration_type_map:
        ret = []
        for i in range(_c_call('size_t', _lib.clingo_configuration_map_size, self._rep, self._key)):
            name = _c_call('char*', _lib.clingo_configuration_map_subkey_name, self._rep, self._key, i)
            ret.append(_to_str(name))
    return ret

Methods

def description(self, name: str) ‑> str

Get a description for an option or option group.

Parameters

name: The name of the option.

Expand source code

def description(self, name: str) -> str:
    '''
    Get a description for an option or option group.

    Parameters
    ----------
    name
        The name of the option.
    '''
    key = self._get_subkey(name)
    if key is None:
        raise RuntimeError(f'unknown option {name}')
    return _to_str(_c_call('char*', _lib.clingo_configuration_description, self._rep, key))