z3/examples/README_quantifier_callbacks.md

UserPropagator Quantifier Instantiation Callback Examples

This directory contains examples demonstrating the UserPropagator callback for quantifier instantiations feature added in Z3 version 4.15.3.

Overview

The quantifier instantiation callback allows user propagators to intercept and control quantifier instantiations, providing fine-grained control over the solving process.

Files

Python Examples

• examples/python/quantifier_instantiation_callback.py - Comprehensive Python examples showing:
  • Basic instantiation control (limiting number of instantiations)
  • Advanced pattern-based filtering
  • Instantiation logging and analysis

C++ Examples

• examples/c++/quantifier_instantiation_callback.cpp - C++ API examples (requires compilation)

C Examples

• examples/c/quantifier_instantiation_callback.c - C API examples (requires compilation)

Unit Tests

• src/test/test_quantifier_instantiation_callback.py - Unit tests validating functionality

Documentation

• doc/quantifier_instantiation_callback.md - Complete API documentation and usage guide

Running the Examples

Python Examples

cd build/python
PYTHONPATH=/path/to/z3/build/python python3 ../../examples/python/quantifier_instantiation_callback.py

Or from the Z3 build directory:

cd build/python
python3 ../../examples/python/quantifier_instantiation_callback.py

C++ Examples

# Compile
g++ -I src/api -I src/api/c++ examples/c++/quantifier_instantiation_callback.cpp -L build -lz3 -o quantifier_callback_cpp

# Run
LD_LIBRARY_PATH=build ./quantifier_callback_cpp

C Examples

# Compile  
gcc -I src/api examples/c/quantifier_instantiation_callback.c -L build -lz3 -o quantifier_callback_c

# Run
LD_LIBRARY_PATH=build ./quantifier_callback_c

Unit Tests

cd z3-root-directory
PYTHONPATH=build/python python3 src/test/test_quantifier_instantiation_callback.py

Expected Output

When running the Python examples, you should see output like:

============================================================
BASIC QUANTIFIER INSTANTIATION CONTROL EXAMPLE
============================================================
Checking satisfiability with instantiation control...
Instantiation #1:
  Quantifier: ForAll(x, f(x) >= 0)
  Instantiation: f(1) >= 0
  -> ALLOWED (#1)

Instantiation #2:
  Quantifier: ForAll(x, f(x) >= 0)
  Instantiation: f(2) >= 0
  -> ALLOWED (#2)

Instantiation #3:
  Quantifier: ForAll(x, f(x) >= 0)
  Instantiation: f(3) >= 0
  -> ALLOWED (#3)

Result: sat
Model: [c = 3, b = 2, a = 1, f = [else -> 0]]

Instantiation Statistics:
  Total attempts: 3
  Allowed: 3
  Blocked: 0

Key Features Demonstrated

1. Basic Control: Limiting the number of quantifier instantiations
2. Pattern Filtering: Allowing only a certain number of instantiations per pattern
3. Logging: Recording all instantiation attempts for analysis
4. Performance Impact: Showing how filtering affects solving time
5. Error Handling: Graceful handling of callback exceptions

Use Cases

• Performance Optimization: Reduce solving time by limiting expensive instantiations
• Custom Strategies: Implement domain-specific instantiation heuristics
• Debugging: Understand solver behavior through instantiation analysis
• Interactive Solving: Dynamically control solving process

Requirements

• Z3 version 4.15.3 or later
• Python 3.x for Python examples
• GCC/Clang for C/C++ examples
• Z3 shared library in LD_LIBRARY_PATH

Troubleshooting

"ModuleNotFoundError: No module named 'z3'"

Set PYTHONPATH to point to the Z3 Python bindings:

export PYTHONPATH=/path/to/z3/build/python:$PYTHONPATH

"No instantiations were attempted"

• Check that your formula contains quantifiers
• Verify that the constraints actually trigger instantiation (e.g., through function applications)
• Try disabling other Z3 optimizations that might eliminate the need for instantiation

C/C++ Compilation Errors

• Ensure Z3 headers are in the include path (-I /path/to/z3/src/api)
• Link against the Z3 library (-L /path/to/z3/build -lz3)
• Set LD_LIBRARY_PATH to find the shared library at runtime

Performance Issues

• Keep callback logic simple and fast
• Avoid expensive string operations in callbacks
• Consider sampling (only process every Nth callback) for high-frequency instantiations

Further Reading

• See doc/quantifier_instantiation_callback.md for complete API documentation
• Z3 Guide: https://microsoft.github.io/z3guide/
• Z3 API Reference: https://z3prover.github.io/api/html/

Contributing

To add new examples or improve existing ones:

1. Follow the existing code style and structure
2. Add appropriate error handling and documentation
3. Include unit tests for new functionality
4. Update this README with any new examples