Add comprehensive documentation and examples for UserPropagator quantifier instantiation callbacks

Co-authored-by: NikolajBjorner <3085284+NikolajBjorner@users.noreply.github.com>

examples/README_quantifier_callbacks.md

@@ -0,0 +1,161 @@
+# 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
+
+```bash
+cd build/python
+PYTHONPATH=/path/to/z3/build/python python3 ../../examples/python/quantifier_instantiation_callback.py
+```
+
+Or from the Z3 build directory:
+```bash
+cd build/python
+python3 ../../examples/python/quantifier_instantiation_callback.py
+```
+
+### C++ Examples
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+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:
+```bash
+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