clingexplaid 1.0.9__tar.gz

clingexplaid-1.0.9/.envrc

@@ -0,0 +1,10 @@
+# automatically activate dev environment when in project tree using direnv.
+ACT=.nox/dev/bin/activate
+
+if [ -e $ACT ]
+then
+    source $ACT
+else
+    echo "Activation script ${ACT} not found for dev environment.
+Run nox -s dev to install dev environment"
+fi

clingexplaid-1.0.9/.github/workflows/deploy.yml

@@ -0,0 +1,51 @@
+name: deploy to pypi
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  deploy:
+    name: deploy
+    needs: test
+    permissions:
+      id-token: write
+    environment: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: install build dependencies
+        run: python3 -m pip install build
+
+      - name: build package
+        run: python3 -m build --sdist --wheel --outdir dist/
+
+      - name: upload package
+        uses: actions/upload-artifact@v4
+        with:
+          name: package
+          path: dist/
+
+      - name: publish package (pypi)
+        if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: "https://upload.pypi.org/legacy/"
+
+      - name: publish package (test.pypi)
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: "https://test.pypi.org/legacy/"

clingexplaid-1.0.9/.github/workflows/test.yml

@@ -0,0 +1,41 @@
+name: run CI test
+
+on:
+  push:
+    branches: [devel, main, master, wip]
+  pull_request:
+  workflow_call:
+
+env:
+  FORCE_COLOR: "3"
+
+jobs:
+  build:
+    name: test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: 3.9
+    - uses: actions/setup-python@v5
+      with:
+        python-version: 3.11
+    - uses: actions/setup-python@v5
+      with:
+        python-version: 3.12
+
+    - name: install requirements
+      run: python -m pip install nox pre-commit
+
+    - name: run pre-commit
+      if: ${{ matrix.os == 'ubuntu-latest' }}
+      run: pre-commit run --all --show-diff-on-failure
+
+    - name: run tests
+      run: nox

clingexplaid-1.0.9/.gitignore

@@ -0,0 +1,40 @@
+# Editors
+.vscode/
+*~
+\#*\#
+.\#*
+.idea/
+
+# Mac/OSX
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.pytest_cache/
+
+#venv
+.venv
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+*egg-info*
+
+# unclassified
+dist
+build
+.coverage
+_build
+_autosummary

clingexplaid-1.0.9/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: https://github.com/myint/autoflake
+    rev: v2.3.0
+    hooks:
+    - id: autoflake
+      args: ["--in-place",  "--imports=clingexplaid", "--ignore-init-module-imports", "--remove-unused-variables"]
+      exclude: ^.github/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+    - id: end-of-file-fixer
+    - id: trailing-whitespace
+      exclude: ^.github/
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        exclude: ^.github/
+
+  - repo: https://github.com/psf/black
+    rev: 24.2.0
+    hooks:
+    - id: black
+      exclude: ^.github/
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.17
+    hooks:
+    - id: mdformat
+      args: ["--wrap", "79"]
+      exclude: ^doc/
+      additional_dependencies:
+      - mdformat-gfm

clingexplaid-1.0.9/.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.9"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: setuptools
+      path: .[doc]

clingexplaid-1.0.9/CHANGES.md

@@ -0,0 +1,5 @@
+# Changes
+
+## v0.1.0
+
+- create project

clingexplaid-1.0.9/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for considering a contribution to clingexplaid. ❤️
+
+## How to get help or discuss possible contributions
+
+To avoid duplicating issues, please search our [issue tracker][issues] and our
+[mailing list][mailing_list] before filing a new issue.
+
+- Open an [issue][new_issue] describing your problem.
+- [Subscribe] to our mailing list on SourceForge.
+
+## How to make a contribution
+
+- Fork the [clingexplaid][project_url] repository and create a branch for your
+  changes.
+- Submit a pull request to the master branch with your changes.
+- Respond to feedback on your pull request.
+- If everything is fine your pull request is merged. 🥳
+
+## License
+
+When contributing to this project, you agree that you have authored 100% of the
+content, that you have the necessary rights to the content and that the content
+you contribute may be provided under the project license.
+
+[issues]: https://github.com/krr-up/clingo-explaidissues/
+[mailing_list]: https://sourceforge.net/p/potassco/mailman/potassco-users/
+[new_issue]: https://github.com/krr-up/clingo-explaidissues/new/
+[project_url]: https://github.com/krr-up/clingo-explaid
+[subscribe]: https://sourceforge.net/projects/potassco/lists/potassco-users/

clingexplaid-1.0.9/DEPLOYMENT.md

@@ -0,0 +1,15 @@
+# Deployment
+
+Releases are deployed on [pypi] whenever a tag of form `vMajor.Minor.Revision`
+is pushed. Furthermore, the deployment workflow can be triggered manually to
+deploy test releases on [test.pypi].
+
+For this to work, the workflow has to be granted permission to deploy on the
+two services. Please follow this packaging [guide] to setup your accounts
+accordingly. We also recommend to setup a github [environment] to restrict
+which contributors can deploy packages.
+
+[environment]: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment/
+[guide]: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+[pypi]: https://pypi.org/
+[test.pypi]: https://test.pypi.org/

clingexplaid-1.0.9/DEVELOPMENT.md

@@ -0,0 +1,41 @@
+# Development
+
+To improve code quality, we use [nox] to run linters, type checkers, unit
+tests, documentation and more. We recommend installing nox using [pipx] to have
+it available globally.
+
+```bash
+# install
+python -m pip install pipx
+python -m pipx install nox
+
+# run all sessions
+nox
+
+# list all sessions
+nox -l
+
+# run individual session
+nox -s session_name
+
+# run individual session (reuse install)
+nox -Rs session_name
+```
+
+Note that the nox sessions create [editable] installs. In case there are
+issues, try recreating environments by dropping the `-R` option. If your
+project is incompatible with editable installs, adjust the `noxfile.py` to
+disable them.
+
+We also provide a [pre-commit][pre] config to autoformat code upon commits. It
+can be set up using the following commands:
+
+```bash
+python -m pipx install pre-commit
+pre-commit install
+```
+
+[editable]: https://setuptools.pypa.io/en/latest/userguide/development_mode.html
+[nox]: https://nox.thea.codes/en/stable/index.html
+[pipx]: https://pypa.github.io/pipx/
+[pre]: https://pre-commit.com/

clingexplaid-1.0.9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hannes Weichelt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clingexplaid-1.0.9/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.1
+Name: clingexplaid
+Version: 1.0.9
+Summary: A template project.
+Author-email: Hannes Weichelt <hweichelt@uni-potsdam.de>
+License: MIT License
+        
+        Copyright (c) 2024 Hannes Weichelt
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/krr-up/clingo-explaid
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: clingo>=5.7.1
+Requires-Dist: autoflake
+Provides-Extra: format
+Requires-Dist: black; extra == "format"
+Requires-Dist: isort; extra == "format"
+Requires-Dist: autoflake; extra == "format"
+Provides-Extra: lint-pylint
+Requires-Dist: pylint; extra == "lint-pylint"
+Provides-Extra: typecheck
+Requires-Dist: types-setuptools; extra == "typecheck"
+Requires-Dist: mypy; extra == "typecheck"
+Provides-Extra: test
+Requires-Dist: coverage[toml]; extra == "test"
+Provides-Extra: doc
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: furo; extra == "doc"
+Requires-Dist: nbsphinx; extra == "doc"
+Requires-Dist: sphinx_copybutton; extra == "doc"
+Requires-Dist: myst-parser; extra == "doc"
+Provides-Extra: dev
+Requires-Dist: clingexplaid[lint_pylint,test,typecheck]; extra == "dev"
+
+# clingexplaid
+
+## Usage
+
+Run the following for basic usage information:
+
+```bash
+clingexplaid -h
+```
+
+The clingexplaid CLI (based on the `clingo.Application` class) can be called
+using this generic command.
+
+```bash
+clingexplaid <filenames> <n> <method> <options>
+```
+
+- `<filenames>`: has to be replaced by a list of all files or a single filename
+- `<n>`: defines how many models are computed (Default=`1`, All=`0`)
+- `<method>`: specifies which Clingexplaid method is used (Required)
+  - Options:
+    - `--muc`:
+      - Computes the Minimal Unsatisfiable Cores (MUCs) of the provided
+        unsatisfiable program
+    - `--unsat-constraints`:
+      - Computes the Unsatisfiable Constraints of the unsatisfiable program
+        provided.
+    - `--show-decisions`:
+      - Visualizes the decision process of clasp
+- `<options>`: Additional options for the different methods
+  - For `--muc`:
+    - `-a`, `--assumption-signature`: limits which facts of the current program
+      are converted to choices/assumptions for finding the MUCs (Default: all
+      facts are converted)
+  - For `--show-decisions`:
+    - `--decision-signature`: limits which decisions are shown in the
+      visualization (Default: all atom's decisions are shown)
+
+### Examples
+
+- A selection of examples can be found [here](examples)
+
+## Development
+
+### Installation
+
+To install the project, run
+
+```bash
+pip install .
+```
+
+To improve code quality, we run linters, type checkers, and unit tests. The
+tools can be run using [nox]. We recommend installing nox using [pipx] to have
+it available globally:
+
+```bash
+python -m pip install pipx
+python -m pipx install nox
+nox
+```
+
+You can invoke `nox -s` to run individual sessions. For example, to install
+your package into a virtual environment and run your test suite, invoke:
+
+```bash
+nox -s test
+```
+
+We also provide a nox session that creates an environment for development. The
+project is installed in [editable] mode into this environment along with
+linting, type checking and formatting tools. Activating it allows your editor
+of choice to access these tools for, e.g., linting and autocompletion. To
+create and then activate virtual environment run:
+
+```bash
+nox -s dev
+source .nox/dev/bin/activate
+```
+
+Furthermore, we provide individual sessions to easily run linting, type
+checking and formatting via nox. These also create editable installs. So you
+can safely skip the recreation of the virtual environment and reinstallation of
+your package in subsequent runs by passing the `-R` command line argument. For
+example, to auto-format your code using [black], run:
+
+```bash
+nox -Rs format -- check
+nox -Rs format
+```
+
+The former command allows you to inspect changes before applying them.
+
+Note that editable installs have some caveats. In case there are issues, try
+recreating environments by dropping the `-R` option. If your project is
+incompatible with editable installs, adjust the `noxfile.py` to disable them.
+
+We also provide a [pre-commit][pre] config to automate this process. It can be
+set up using the following commands:
+
+```bash
+python -m pipx install pre-commit
+pre-commit install
+```
+
+This blackens the source code whenever `git commit` is used.
+
+## Problems and Limitations
+
+### Meta-encoding based approach (ASP-Approach)
+
+**Important Notes:**
+
+- The Meta-encoding approach as it stands is not fully functional
+
+**Problem:**
+
+- In the meta encoding all facts (or a selection matching a certain signature)
+  are transformed into assumptions which are then used as the assumption set
+  for finding the MUC
+- During the MUC search when subsets of this assumption set are fixed for
+  satisfiability checking it is important that even though they are not fixed,
+  the other assumptions are not assumed as false but as undefined
+- This is currently not possible with the meta-encoding, since assumptions are
+  chosen through a choice rule and all assumptions that aren't selected are
+  defaulted to false
+- This doesn't allow for properly checking if such subsets entail
+  unsatisfiability and thus prevents us from finding the proper MUCs
+
+### Specifying Assumption Set using only Signatures
+
+**Important Notes:**
+
+- clingo-explaid provides the `--muc` mode which gives you Minimal
+  Unsatisfiable Cores for a given set of assumption signatures that can be
+  defined with `-a`
+- These signatures though allow not always for finding the best fitting MUC for
+  a given encoding, compared to an assumption set generated by hand
+
+**Problem:**
+
+- Imagine this [example encoding](examples/misc/bad_mucs.lp):
+
+```MATLAB
+a(1..3).
+:- a(X).
+
+unsat.
+:- unsat.
+```
+
+- So when I execute `clingexplaid examples/misc/bad_mucs.lp --muc 0` I get the
+  MUCs:
+
+```
+MUC 1
+a(3)
+MUC 2
+a(2)
+MUC 3
+a(1)
+MUC 4
+unsat
+```
+
+- So you would generally expect that executing
+  `clingexplaid examples/misc/bad_mucs.lp --muc 0 -a/1` would return the first
+  3 found MUCs from before
+- But what actually happens is that there are no MUCs detected:
+
+```
+NO MUCS CONTAINED: The unsatisfiability of this program is not induced by the provided assumptions
+UNSATISFIABLE
+```
+
+- This is actually due to an implicit `(unsat, False)` in the first 3 MUCs that
+  isn't printed
+- Since the standard mode of `--muc` converts all facts to choices when no `-a`
+  is provided `a(1)`, `a(2)`, `a(3)`, and `unsat` are all converted to choices
+- We know that for the program to become satisfiable `unsat` cannot be true
+  (line 4)
+- But since it is provided as a fact the choice rule conversion is necessary
+  for the iterative deletion algorithm to find any MUCs
+- This holds vice versa for the last MUC 4 just so that all `a/1` need to be
+  converted to choice rules for the MUC to be found
+
+[black]: https://black.readthedocs.io/en/stable/
+[editable]: https://setuptools.pypa.io/en/latest/userguide/development_mode.html
+[nox]: https://nox.thea.codes/en/stable/index.html
+[pipx]: https://pypa.github.io/pipx/
+[pre]: https://pre-commit.com/