d4Solver 1.0.0__tar.gz

d4solver-1.0.0/.gitignore

@@ -0,0 +1,38 @@
+# --- CMake / Build directories ---
+build/
+cmake-build-debug/
+cmake-build-release/
+.cmake/
+CMakeFiles/
+CMakeCache.txt
+Makefile
+cmake_install.cmake
+
+# --- Compiled shared libraries / binaries ---
+*.so
+*.dylib
+*.dll
+*.pyd
+py_d4/_py_d4*.so
+
+# --- Python packaging & caching ---
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.eggs/
+.egg-info/
+*.egg-info/
+dist/
+wheelhouse/
+venv/
+.venv/
+env/
+
+# --- IDEs and editor configurations ---
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store

d4solver-1.0.0/.gitlab-ci.yml

@@ -0,0 +1,140 @@
+stages:
+  - build
+  - deploy
+
+build_wheels_linux:
+  stage: build
+  tags:
+    - linux
+  image: docker:24.0.7
+  services:
+    - name: docker:24.0.7-dind
+      alias: docker
+  variables:
+    DOCKER_HOST: "tcp://docker:2375"
+    DOCKER_TLS_CERTDIR: ""
+    DOCKER_DRIVER: overlay2
+    PIP_BREAK_SYSTEM_PACKAGES: "1"
+    CMAKE_BUILD_PARALLEL_LEVEL: "2"
+    CIBW_ENVIRONMENT_PASS_LINUX: "GITLAB_TOKEN_D4 GITLAB_TOKEN GITLAB_TOKEN_LOGICAL CMAKE_BUILD_PARALLEL_LEVEL D4_GIT_TAG D4_GIT_URL"
+  before_script:
+    # Détection automatique du socket Docker local ou du service TCP
+    - |
+      if ! docker info >/dev/null 2>&1; then
+        echo "Docker TCP host ($DOCKER_HOST) unreachable, unsetting DOCKER_HOST to use local socket..."
+        unset DOCKER_HOST
+      fi
+      for i in $(seq 1 30); do
+        docker info >/dev/null 2>&1 && break || sleep 1
+      done
+    # Configuration simplifiée des jetons et tags
+    - |
+      export GITLAB_TOKEN_D4="${GITLAB_TOKEN_LOGICAL:-$CI_JOB_TOKEN}"
+      export GITLAB_TOKEN="${GITLAB_TOKEN_LOGICAL:-$CI_JOB_TOKEN}"
+      if [ -n "$CI_COMMIT_TAG" ]; then
+        export D4_GIT_TAG="${GITHUB_D4_TAG:-$CI_COMMIT_TAG}"
+        if echo "$D4_GIT_TAG" | grep -q '^[0-9]'; then
+          export D4_GIT_TAG="v$D4_GIT_TAG"
+        fi
+        export D4_GIT_URL="${GITHUB_D4_URL:-$D4_GIT_URL}"
+      else
+        export D4_GIT_TAG="master"
+        unset D4_GIT_URL
+      fi
+    - apk add --no-cache python3 py3-pip
+  script:
+    - |
+      if [ -n "$CI_COMMIT_TAG" ]; then
+        VERSION=$(echo "$CI_COMMIT_TAG" | sed 's/^v//')
+        echo "GitLab Tag detected: $CI_COMMIT_TAG -> Version: $VERSION"
+        VERSION="$VERSION" python3 -c "import re, os; p = 'pyproject.toml'; c = open(p).read(); open(p, 'w').write(re.sub(r'^version\s*=\s*\"[^\"]+\"', f'version = \"{os.environ[\"VERSION\"]}\"', c, count=1, flags=re.M))"
+        echo "Updated pyproject.toml version to $VERSION"
+      fi
+    - pip install cibuildwheel
+    - cibuildwheel --output-dir wheelhouse
+  artifacts:
+    paths:
+      - wheelhouse/
+    expire_in: 1 week
+
+build_wheels_windows:
+  stage: build
+  tags:
+    - windows
+    - msvc
+  variables:
+    CMAKE_TOOLCHAIN_FILE: "C:/vcpkg/scripts/buildsystems/vcpkg.cmake"
+    CMAKE_BUILD_PARALLEL_LEVEL: "2"
+    CIBW_ENVIRONMENT_PASS_WINDOWS: "GITLAB_TOKEN_D4 GITLAB_TOKEN GITLAB_TOKEN_LOGICAL CMAKE_TOOLCHAIN_FILE CMAKE_BUILD_PARALLEL_LEVEL CIBW_REPAIR_WHEEL_COMMAND_WINDOWS D4_GIT_TAG D4_GIT_URL"
+  before_script:
+    - '$PROJECT_DIR = (Get-ChildItem -Path "C:\GitLab-Runner\builds" -Filter "pyproject.toml" -Recurse -File | Select-Object -First 1).DirectoryName'
+    - 'cd $PROJECT_DIR'
+    - '$env:GITLAB_TOKEN_LOGICAL = "glpat-eHavaAslBimi87EABf6MIW86MQp1OjJpdgk.01.0z0dxf0ko"'
+    - '$env:GITLAB_TOKEN_D4 = "glpat-eHavaAslBimi87EABf6MIW86MQp1OjJpdgk.01.0z0dxf0ko"'
+    - '$env:GITLAB_TOKEN = "glpat-eHavaAslBimi87EABf6MIW86MQp1OjJpdgk.01.0z0dxf0ko"'
+    - '$env:CMAKE_TOOLCHAIN_FILE = "C:/vcpkg/scripts/buildsystems/vcpkg.cmake"'
+    - '$env:CIBW_REPAIR_WHEEL_COMMAND_WINDOWS = "delvewheel repair --add-path C:\vcpkg\installed\x64-windows\bin -w {dest_dir} {wheel}"'
+    - '$env:D4_GIT_TAG = if ($env:CI_COMMIT_TAG) { if ($env:GITHUB_D4_TAG) { $env:GITHUB_D4_TAG } else { $env:CI_COMMIT_TAG } } else { "master" }'
+    - 'if ($env:CI_COMMIT_TAG -and ($env:D4_GIT_TAG -match "^[0-9]")) { $env:D4_GIT_TAG = "v" + $env:D4_GIT_TAG }'
+    - '$env:D4_GIT_URL = if ($env:CI_COMMIT_TAG) { if ($env:GITHUB_D4_URL) { $env:GITHUB_D4_URL } else { $env:D4_GIT_URL } } else { $null }'
+    - 'if ($env:CI_COMMIT_TAG) { $env:VERSION = $env:CI_COMMIT_TAG -replace "^v", ""; Write-Host "GitLab Tag detected: $env:CI_COMMIT_TAG -> Version: $env:VERSION"; python -c "import re, os; p = \"pyproject.toml\"; c = open(p).read(); open(p, \"w\").write(re.sub(r\"^version\s*=\s*\\\"[^\\\"]+\\\"\", f\"version = \\\"{os.environ[\\\"VERSION\\\"]}\\\"\", c, count=1, flags=re.M))" }'
+    - python -m pip install cibuildwheel
+  script:
+    - '$PROJECT_DIR = (Get-ChildItem -Path "C:\GitLab-Runner\builds" -Filter "pyproject.toml" -Recurse -File | Select-Object -First 1).DirectoryName'
+    - 'cd $PROJECT_DIR'
+    - '$env:GITLAB_TOKEN_LOGICAL = "glpat-eHavaAslBimi87EABf6MIW86MQp1OjJpdgk.01.0z0dxf0ko"'
+    - '$env:GITLAB_TOKEN_D4 = "glpat-eHavaAslBimi87EABf6MIW86MQp1OjJpdgk.01.0z0dxf0ko"'
+    - '$env:GITLAB_TOKEN = "glpat-eHavaAslBimi87EABf6MIW86MQp1OjJpdgk.01.0z0dxf0ko"'
+    - '$env:CMAKE_TOOLCHAIN_FILE = "C:/vcpkg/scripts/buildsystems/vcpkg.cmake"'
+    - '$env:CIBW_REPAIR_WHEEL_COMMAND_WINDOWS = "delvewheel repair --add-path C:\vcpkg\installed\x64-windows\bin -w {dest_dir} {wheel}"'
+    - '$env:D4_GIT_TAG = if ($env:CI_COMMIT_TAG) { if ($env:GITHUB_D4_TAG) { $env:GITHUB_D4_TAG } else { $env:CI_COMMIT_TAG } } else { "master" }'
+    - 'if ($env:CI_COMMIT_TAG -and ($env:D4_GIT_TAG -match "^[0-9]")) { $env:D4_GIT_TAG = "v" + $env:D4_GIT_TAG }'
+    - '$env:D4_GIT_URL = if ($env:CI_COMMIT_TAG) { if ($env:GITHUB_D4_URL) { $env:GITHUB_D4_URL } else { $env:D4_GIT_URL } } else { $null }'
+    - 'cibuildwheel --output-dir wheelhouse'
+  artifacts:
+    paths:
+      - wheelhouse/
+    expire_in: 1 week
+
+build_sdist:
+  stage: build
+  tags:
+    - linux
+  image: python:3.10-slim
+  script:
+    - pip install build
+    - |
+      if [ -n "$CI_COMMIT_TAG" ]; then
+        VERSION=$(echo "$CI_COMMIT_TAG" | sed 's/^v//')
+        echo "GitLab Tag detected: $CI_COMMIT_TAG -> Version: $VERSION"
+        VERSION="$VERSION" python3 -c "import re, os; p = 'pyproject.toml'; c = open(p).read(); open(p, 'w').write(re.sub(r'^version\s*=\s*\"[^\"]+\"', f'version = \"{os.environ[\"VERSION\"]}\"', c, count=1, flags=re.M))"
+        echo "Updated pyproject.toml version to $VERSION"
+      fi
+    - python3 -m build --sdist --outdir wheelhouse/
+  artifacts:
+    paths:
+      - wheelhouse/
+    expire_in: 1 week
+
+publish_to_gitlab:
+  stage: deploy
+  tags:
+    - linux
+  image: python:3.10-slim
+  script:
+    - pip install twine
+    - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --verbose --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi wheelhouse/*
+  only:
+    - tags
+
+publish_to_pypi:
+  stage: deploy
+  tags:
+    - linux
+  image: python:3.10-slim
+  script:
+    - pip install twine
+    - TWINE_USERNAME=__token__ TWINE_PASSWORD=${PYPI_API_TOKEN} python -m twine upload --verbose wheelhouse/*
+  rules:
+    - if: $CI_COMMIT_TAG
+

d4solver-1.0.0/CMakeLists.txt

@@ -0,0 +1,240 @@
+cmake_minimum_required(VERSION 3.15)
+project(py-d4 LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+if(MSVC)
+    add_compile_definitions(NOMINMAX)
+    add_compile_definitions(popen=_popen)
+    add_compile_definitions(pclose=_pclose)
+endif()
+
+if(POLICY CMP0097)
+    cmake_policy(SET CMP0097 NEW)
+endif()
+
+# -----------------------------------------------------------------------------
+# 1. Fetch (or reuse) D4
+# -----------------------------------------------------------------------------
+include(FetchContent)
+set(FETCHCONTENT_BASE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_deps" CACHE PATH "Directory for FetchContent" FORCE)
+
+# Allow overriding with a local D4 source directory (avoids network fetch)
+# Usage: cmake -DD4_LOCAL_PATH=/path/to/d4 ..
+set(D4_LOCAL_PATH "" CACHE PATH "Path to a local D4 source directory (skips FetchContent clone)")
+
+# Allow overriding with a local optree source directory (avoids network fetch)
+# Usage: cmake -DOPTREE_LOCAL_PATH=/path/to/optree .. or export OPTREE_LOCAL_PATH=/path/to/optree
+set(OPTREE_LOCAL_PATH "" CACHE PATH "Path to a local optree source directory")
+if (DEFINED ENV{OPTREE_LOCAL_PATH} AND NOT OPTREE_LOCAL_PATH)
+    set(OPTREE_LOCAL_PATH "$ENV{OPTREE_LOCAL_PATH}")
+endif()
+
+if (D4_LOCAL_PATH AND EXISTS "${D4_LOCAL_PATH}/CMakeLists.txt")
+    message(STATUS "Using local D4 source at: ${D4_LOCAL_PATH}")
+    FetchContent_Declare(
+        d4
+        SOURCE_DIR "${D4_LOCAL_PATH}"
+    )
+else()
+    # Propagate token to optree (D4's internal dependency) environment variable
+    if (DEFINED ENV{GITLAB_TOKEN_LOGICAL} AND NOT DEFINED ENV{GITLAB_TOKEN})
+        set(ENV{GITLAB_TOKEN} "$ENV{GITLAB_TOKEN_LOGICAL}")
+    elseif (DEFINED ENV{GITLAB_TOKEN_D4} AND NOT DEFINED ENV{GITLAB_TOKEN})
+        set(ENV{GITLAB_TOKEN} "$ENV{GITLAB_TOKEN_D4}")
+    endif()
+
+    if (DEFINED ENV{GITLAB_TOKEN} AND NOT DEFINED ENV{GITLAB_TOKEN_LOGICAL})
+        set(ENV{GITLAB_TOKEN_LOGICAL} "$ENV{GITLAB_TOKEN}")
+    elseif (DEFINED ENV{GITLAB_TOKEN_D4} AND NOT DEFINED ENV{GITLAB_TOKEN_LOGICAL})
+        set(ENV{GITLAB_TOKEN_LOGICAL} "$ENV{GITLAB_TOKEN_D4}")
+    endif()
+
+    # Inject token or custom URL from environment variable if available
+    if (DEFINED ENV{D4_GIT_URL} AND NOT "$ENV{D4_GIT_URL}" STREQUAL "")
+        set(D4_GIT_URL "$ENV{D4_GIT_URL}")
+        message(STATUS "Using custom D4 Git URL from environment variable: ${D4_GIT_URL}")
+    elseif (DEFINED ENV{GITLAB_TOKEN_D4})
+        set(D4_GIT_URL "https://oauth2:$ENV{GITLAB_TOKEN_D4}@gitlab.univ-artois.fr/logical/d4.git")
+        message(STATUS "Using authenticated GitLab URL for D4 (token from env GITLAB_TOKEN_D4)")
+    elseif (DEFINED ENV{GITLAB_TOKEN_LOGICAL})
+        set(D4_GIT_URL "https://oauth2:$ENV{GITLAB_TOKEN_LOGICAL}@gitlab.univ-artois.fr/logical/d4.git")
+        message(STATUS "Using authenticated GitLab URL for D4 (token from env GITLAB_TOKEN_LOGICAL)")
+    else()
+        set(D4_GIT_URL "https://gitlab.univ-artois.fr/logical/d4.git")
+        message(STATUS "No GITLAB_TOKEN_D4 or GITLAB_TOKEN_LOGICAL env variable set — using unauthenticated URL for D4")
+    endif()
+
+    # Allow overriding D4 git tag/branch via CMake variable or environment variable
+    set(D4_GIT_TAG "master" CACHE STRING "Git tag/branch for fetching D4")
+    if (DEFINED ENV{D4_GIT_TAG} AND NOT "$ENV{D4_GIT_TAG}" STREQUAL "")
+        set(D4_GIT_TAG "$ENV{D4_GIT_TAG}")
+    endif()
+    message(STATUS "D4 Git tag/branch set to: ${D4_GIT_TAG}")
+
+    FetchContent_Declare(
+        d4
+        GIT_REPOSITORY ${D4_GIT_URL}
+        GIT_TAG        ${D4_GIT_TAG}
+        GIT_SHALLOW    TRUE
+        GIT_SUBMODULES ""
+    )
+endif()
+
+# Fetch, patch and integrate D4 as a subdirectory.
+FetchContent_GetProperties(d4)
+if(NOT d4_POPULATED)
+    # CMP0169: FetchContent_Populate with declared details was deprecated in
+    # CMake 3.30. We set the policy to OLD so that the call below continues
+    # to work until we can migrate to a cleaner solution.
+    if(POLICY CMP0169)
+        cmake_policy(SET CMP0169 OLD)
+    endif()
+    FetchContent_Populate(d4)
+
+    set(D4_CMAKELISTS "${d4_SOURCE_DIR}/CMakeLists.txt")
+    if(EXISTS "${D4_CMAKELISTS}")
+        file(READ "${D4_CMAKELISTS}" _d4_cmake)
+
+        # Patch: do not force static ZLIB inside the python wrapper (which compiles a shared module)
+        string(REPLACE
+            "set(ZLIB_USE_STATIC_LIBS ON)"
+            "if(CMAKE_PROJECT_NAME STREQUAL \"D4\")\n            set(ZLIB_USE_STATIC_LIBS ON)\n        endif()"
+            _d4_cmake "${_d4_cmake}")
+
+        # Patch: use local optree source directory if specified and exists
+        if (OPTREE_LOCAL_PATH AND EXISTS "${OPTREE_LOCAL_PATH}/CMakeLists.txt")
+            string(REPLACE
+                "GIT_REPOSITORY \${OPTREE_GIT_URL}\n    GIT_TAG        main"
+                "SOURCE_DIR \"${OPTREE_LOCAL_PATH}\""
+                _d4_cmake "${_d4_cmake}")
+        endif()
+
+        # Patch: remove unused variable 'nb' in DpllStyleMethod.hpp to avoid compiler warnings
+        set(D4_DPLL_STYLE_METHOD "${d4_SOURCE_DIR}/src/methods/DpllStyleMethod.hpp")
+        if(EXISTS "${D4_DPLL_STYLE_METHOD}")
+            file(READ "${D4_DPLL_STYLE_METHOD}" _dpll_content)
+            string(REPLACE
+                "unsigned nb = 0, sizeAssum = m_solver->sizeAssumption();"
+                "unsigned sizeAssum = m_solver->sizeAssumption();"
+                _dpll_content "${_dpll_content}")
+            string(REPLACE
+                "int tmp = m_nbCallCall;"
+                "// int tmp = m_nbCallCall;"
+                _dpll_content "${_dpll_content}")
+            file(WRITE "${D4_DPLL_STYLE_METHOD}" "${_dpll_content}")
+        endif()
+
+        file(WRITE "${D4_CMAKELISTS}" "${_d4_cmake}")
+    endif()
+
+    # Patch D4 option headers to fix include paths on older branches (like master)
+    file(GLOB _option_files "${d4_SOURCE_DIR}/src/options/methods/Option*.hpp")
+    foreach(_opt_file ${_option_files})
+        if(EXISTS "${_opt_file}")
+            file(READ "${_opt_file}" _opt_content)
+            string(REPLACE
+                "options/solvers/OptionSolver.hpp"
+                "solvers/OptionSolver.hpp"
+                _opt_content "${_opt_content}")
+            file(WRITE "${_opt_file}" "${_opt_content}")
+        endif()
+    endforeach()
+
+    add_subdirectory(${d4_SOURCE_DIR} ${d4_BINARY_DIR})
+    add_subdirectory("${d4_SOURCE_DIR}/3rdParty/cadical" "${CMAKE_CURRENT_BINARY_DIR}/cadical_build")
+    target_compile_definitions(cadical PRIVATE NCLOSEFROM)
+endif()
+
+message(STATUS "D4 source dir: ${d4_SOURCE_DIR}")
+message(STATUS "D4 binary dir: ${d4_BINARY_DIR}")
+
+# -----------------------------------------------------------------------------
+# 2. Setup Nanobind & Python
+# -----------------------------------------------------------------------------
+find_package(Python 3.8 COMPONENTS Interpreter Development.Module REQUIRED)
+
+find_package(nanobind CONFIG QUIET)
+if (NOT nanobind_FOUND)
+    message(STATUS "nanobind not found. Fetching it...")
+    FetchContent_Declare(
+        nanobind
+        GIT_REPOSITORY https://github.com/wjakob/nanobind.git
+        GIT_TAG        v2.0.0
+    )
+    FetchContent_MakeAvailable(nanobind)
+endif()
+
+# Find or fetch nlohmann_json
+find_package(nlohmann_json QUIET)
+if (NOT nlohmann_json_FOUND)
+    message(STATUS "nlohmann_json not found. Fetching it...")
+    FetchContent_Declare(
+        json
+        GIT_REPOSITORY https://github.com/nlohmann/json.git
+        GIT_TAG        v3.11.3
+    )
+    FetchContent_MakeAvailable(json)
+endif()
+
+# -----------------------------------------------------------------------------
+# 3. Auto-generate C++ definitions and Python bindings
+# -----------------------------------------------------------------------------
+add_custom_target(
+    py_d4_generate_bindings
+    COMMAND "${Python_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/generate_binding_hpp.py" "${d4_SOURCE_DIR}"
+    COMMAND "${Python_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/generate_bindings.py" "${d4_SOURCE_DIR}"
+    COMMAND "${Python_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/generate_runner_bindings.py" "${d4_SOURCE_DIR}"
+    COMMENT "Auto-generating options C++ definitions and Python bindings..."
+    VERBATIM
+)
+
+# -----------------------------------------------------------------------------
+# 4. Define Nanobind Module
+# -----------------------------------------------------------------------------
+nanobind_add_module(
+    _py_d4
+    NB_STATIC
+    src/wrapper.cpp
+    src/generated_bindings.cpp
+    src/generated_runner_bindings.cpp
+    "${d4_SOURCE_DIR}/api/solver/Solver.cpp"
+    "${d4_SOURCE_DIR}/c++/parser/ParserDimacs.cpp"
+    "${d4_SOURCE_DIR}/c++/parser/ParserCircuit.cpp"
+)
+
+# Ensure bindings are generated before compiling the module
+add_dependencies(_py_d4 py_d4_generate_bindings)
+
+# Link against the d4::d4 target, nlohmann_json, and cadical
+target_link_libraries(_py_d4 PRIVATE d4::d4 nlohmann_json::nlohmann_json cadical)
+
+if(WIN32)
+    # Link psapi for GetProcessMemoryInfo used in CaDiCaL
+    target_link_libraries(_py_d4 PRIVATE psapi)
+    
+    # Link gmpxx on Windows (needed for GMP ostream operators)
+    find_library(GMPXX_LIBRARY NAMES gmpxx libgmpxx REQUIRED)
+    target_link_libraries(_py_d4 PRIVATE ${GMPXX_LIBRARY})
+endif()
+
+# Include paths: our src/ + D4's source tree (for headers)
+target_include_directories(_py_d4 PRIVATE
+    "${CMAKE_CURRENT_SOURCE_DIR}/src"
+    "${d4_SOURCE_DIR}/src"
+)
+install(TARGETS _py_d4 DESTINATION py_d4)
+
+# Generate Python autocomplete/stub files (.pyi) post-build
+add_custom_command(
+    TARGET _py_d4 POST_BUILD
+    COMMAND "${Python_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/generate_stubs.py" _py_d4 "${CMAKE_CURRENT_BINARY_DIR}"
+    WORKING_DIRECTORY $<TARGET_FILE_DIR:_py_d4>
+    COMMENT "Generating autocomplete/type stub file (_py_d4.pyi)..."
+    VERBATIM
+)
+
+# Install the generated stub file
+install(FILES "${CMAKE_CURRENT_BINARY_DIR}/_py_d4.pyi" DESTINATION py_d4 OPTIONAL)

d4solver-1.0.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.2
+Name: d4Solver
+Version: 1.0.0
+Summary: Python bindings for the D4 model counter and compiler
+Author-Email: Logical Team <contact@univ-artois.fr>
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# py-d4
+
+Python bindings for the **D4** compiler and model counter, supporting option structures, CNF files, custom clause vectors, logic circuits, weighted model counting, and d-DNNF queries. Built with `nanobind` and `scikit-build-core`.
+
+---
+
+## 🚀 Users Guide
+
+### 1. Installation
+
+Install the package directly from your GitLab PyPI package registry (typically configured in your CI or local `.pip/pip.conf`):
+
+```bash
+pip install d4Solver --extra-index-url https://gitlab.univ-artois.fr/api/v4/projects/<PROJECT_ID>/packages/pypi/simple
+```
+
+### 2. Usage Examples
+
+#### 2.1 Basic Model Counting
+
+You can instantiate a `Solver` using a CNF filepath or raw Python clause structures (list of lists/tuples of literals, 1-based indexing):
+
+```python
+import py_d4
+
+# 1. Option A: Load from a DIMACS CNF file
+solver = py_d4.Solver("path/to/formula.cnf")
+
+# 2. Option B: Pass raw Python clauses and total variable count
+# Formula: (x1 or x2) and (not x2 or x3)
+clauses = [
+    [1, 2],
+    [-2, 3]
+]
+nb_vars = 3
+solver = py_d4.Solver(clauses, nb_vars)
+
+# Run model counting
+count_res = solver.count()
+print(f"Number of models: {count_res.getResult()}")     # Large integer as string (GMP support)
+print(f"As Python integer: {count_res.getIntResult()}")  # Safe python int
+```
+
+#### 2.2 Compilation to d-DNNF
+
+`py-d4` can compile CNF formulas and circuits into Decision Diagram / Deterministic Decomposable Negation Normal Form (d-DNNF):
+
+```python
+import py_d4
+
+clauses = [[1, 2], [-2, 3]]
+solver = py_d4.Solver(clauses, 3)
+
+# Compile
+compile_res = solver.compile()
+
+# Access compiled graph statistics
+print(f"Nodes in d-DNNF: {compile_res.getNbNodes()}")
+print(f"Edges in d-DNNF: {compile_res.getNbEdges()}")
+
+# Get the compiled NNF circuit string (in standard d-DNNF format)
+nnf_str = compile_res.getNNFString()
+print("NNF String:\n", nnf_str)
+```
+
+#### 2.3 Querying the Compiled d-DNNF
+
+Once compiled, you can run multiple queries (SAT checks or model counting) under different literal assumptions:
+
+```python
+# Check if the formula is satisfiable (no assumptions)
+is_sat = compile_res.isSAT([])  # True/False
+
+# Check satisfiability assuming x1 is True (1) and x2 is False (-2)
+is_sat_under_assumptions = compile_res.isSAT([1, -2])
+
+# Count models under literal assumptions
+# E.g., model count assuming x1 is True
+count_under_x1 = compile_res.count([1])
+print(f"Models satisfying x1: {count_under_x1}")
+```
+
+#### 2.4 Weighted Model Counting (WMC)
+
+You can assign weights to literals for exact weighted model counting:
+
+```python
+import py_d4
+
+# Formula: (x1 or x2)
+solver = py_d4.Solver([[1, 2]], nb_vars=2)
+
+# Define weights for literals (keys are 1-based literals, values are string representations)
+weights = {
+    1: "0.3",
+    -1: "0.7",
+    2: "0.4",
+    -2: "0.6"
+}
+# Set weights (WeightType can be FLOAT or GMP)
+solver.setWeights(weights, py_d4.WeightType.FLOAT)
+
+# Compute WMC directly
+count_res = solver.count()
+print("WMC Result:", float(count_res.getResult()))  # Output: 0.58
+
+# Or compile and query WMC under assumptions
+compile_res = solver.compile()
+print("WMC under x1=True:", float(compile_res.count([1])))  # Output: 0.3
+```
+
+#### 2.5 Logic Gates / Circuit Compilation
+
+Instead of CNF, you can initialize the solver with logic gates to compile or count structured circuits:
+
+```python
+import py_d4
+
+# Create a gate representing: x3 = x1 AND (not x2)
+gate = py_d4.Gate()
+gate.gateType = py_d4.GateType.AND
+gate.inputs = [1, -2]
+gate.output = 3
+
+# Instantiate solver from gate specifications
+solver = py_d4.Solver([gate], nb_vars=3)
+print("Models for circuit:", solver.count().getIntResult())
+```
+
+#### 2.6 Solver Configuration & Options
+
+Fine-tune the behavior of D4 by mutating native C++ option structures. Documentation and description of settings are exposed natively as Python docstrings:
+
+```python
+import py_d4
+
+# Instantiate default options
+opt = py_d4.OptionDpllStyleMethod()
+
+# 1. Read Option Descriptions (C++ docstrings exposed to Python)
+print(py_d4.OptionDpllStyleMethod.exploitModel.__doc__)
+# Output: "If we exploit model during search"
+
+# 2. Modify properties directly (with type safety)
+opt.precision = 30
+opt.exploitModel = False
+opt.optionSolver.solverName = 0  # 0: glucose, 1: minisat
+
+# 3. Modify nested option group settings
+opt.optionBranchingHeuristic.freqDecay = 98
+
+# 4. Pass options to the Solver
+solver = py_d4.Solver("formula.cnf", opt)
+
+# 5. Serialize options to/from standard Python Dictionaries
+config_dict = py_d4.dump_options_to_dict(opt)
+opt_restored = py_d4.load_options_from_dict(config_dict)
+
+# 6. Serialize options to/from raw JSON Strings (via native C++ bindings)
+json_str = py_d4._py_d4.dump_options_to_json(opt)
+opt_restored_json = py_d4._py_d4.load_options_from_json(json_str)
+```
+
+---
+
+## 🛠️ Developers Guide
+
+### 1. Requirements
+
+Before building locally, ensure the following system-level dependencies are installed on your host:
+- C++20 compatible compiler (e.g. GCC >= 10, Clang >= 10)
+- CMake (>= 3.15)
+- GMP development headers (`libgmp-dev` / `gmp-devel`)
+- Zlib development headers (`zlib1g-dev` / `zlib-devel`)
+
+### 2. Local Build Pipeline
+
+To compile the C++ extension module and deploy it directly inside your local Python package tree, run:
+
+```bash
+# 1. Provide your GitLab access token to clone the D4 dependency
+export GITLAB_TOKEN_LOGICAL="your_gitlab_token"
+
+# 2. Configure, generate bindings, compile, and deploy shared library
+./build.sh
+```
+
+Alternatively, you can install the package in editable mode via pip:
+```bash
+pip install -e .
+```
+
+### 3. Re-Generating Bindings
+
+If D4 option headers change, you can automatically parse the new C++ classes and inline constructor descriptions to rebuild the `nanobind` bindings:
+
+```bash
+python3 scripts/generate_bindings.py /path/to/local/d4
+```
+*(If `/path/to/local/d4` is omitted, the script automatically searches the CMake FetchContent directory).*
+
+### 4. Running Tests
+
+To execute the test suite and verify the integrity of the wrapper:
+
+```bash
+LD_PRELOAD=$(gcc -print-file-name=libstdc++.so.6) PYTHONPATH=. python3 tests/test_options.py
+```
+
+### 5. GitLab CI/CD Pipeline
+
+The project includes an automated multi-stage `.gitlab-ci.yml` pipeline:
+- **Build Stage**: Uses `cibuildwheel` to compile optimized, standalone Linux wheels for Python 3.8 to 3.13. It automatically routes the group-level `GITLAB_TOKEN_LOGICAL` CI variable to authenticate both the `py-d4` and internal `d4`/`optree` sub-project checkouts.
+- **Deploy Stage**: Triggered on pushing Git tags. Automatically publishes the generated wheel packages directly to the GitLab project PyPI package registry using `twine`.