44966e1733
* first attempt with codex. Codex notes:
What changed:
- Each tree node now tracks:
- active worker count
- lease epoch
- cancel epoch
- get_cube() now hands each worker an explicit lease: (node, epoch, cancel_epoch).
- try_split() and backtrack() now operate on that lease, and the batch manager releases the worker’s lease under the tree lock before mutating the
node.
- If another worker closes the leased node or subtree, the batch manager cancels only the workers whose current leased nodes are now closed.
- Workers detect canceled leases after check(), reset their local cancel flag, abandon the stale lease, and continue instead of turning that into a
global exception.
- The “reopen immediately into the open queue” policy is preserved. I did not add a barrier waiting for all workers on a node to finish.
- Active-worker accounting is now separate from the open/active/closed scheduling status, so reopening a node no longer erases the fact that other
workers are still on it.
I also updated search_tree bookkeeping so:
- closure bumps node cancel/lease epochs
- active-node counting uses actual active-worker presence, not just status == active
* fix(parallel-smt): gate split/backtrack by lease epoch
What it changes:
- util/search_tree.h
- bumps node epoch on split
- threads epoch through should_split(...) and try_split(...)
- always records effort, but only split/reopen if the lease epoch still matches
- smt/smt_parallel.cpp
- requires is_lease_valid(..., lease.epoch) before backtrack(...)
- passes lease.epoch into m_search_tree.try_split(...)
* clean up code and add some comments
* fix bug about backtracking condition being too strict: The epoch guard should not block backtrack(...) the same way it blocks try_split(...). A stale worker that proves UNSAT for n should still be able to
close n, and that closure should then cancel the other workers on n and its subtree.
I changed smt/smt_parallel.cpp accordingly:
- try_split(...) still uses epoch to reject stale structural splits
- backtrack(...) no longer requires is_lease_valid(..., epoch); it only requires that the lease is not already canceled
So the intended asymmetry is now restored:
- stale split: reject
- stale unsat/backtrack: allow closure, then cancel affected workers
* ablate to no backtracking on stale leases
* revert codex change about exception handling
* remove old code
* ablate backtracking gate
* attempt to fix linux crashes
* try to fix bug about active worker counts/lease accounting. current policy should hold: - stale leases: release/decrement
- canceled leases: do not release/decrement (just ignore since we have an invariant that canceled leases mean closed nodes that are never revisited
* delay premature root activation
* fix major semantic bug about threads continually choosing the root if their lease is reset
* fix cancellation to unknown status
* fix very bad bug about all threads needing to start at the root
* ablate active ranking: now nodes are only reopened if they are truly inactive (active worker count is 0)
* fix some bugs about leases
* ablate adding static effort only
* fix some bugs about leases
* don't explode effort for portfolio nodes
* fix: still accumulate per-node effort, but don't over-accumulate on portfolio solves
* restore dynamically scaled effort
* lease cancellation doens't touch rlimit now, it just sets max conflicts to 0. also fix a VERY BAD BUG about effort never being updated until all leases are done on a node, which meant we never left the root
* cross-thread modification of max conflicts is unsafe, so create an atomic lease canceled variable that's ch
ecked in ctx where max conflicts is also checked
* move atomic lease check in the context to the more global get_cancel_flag function
* Fix new SIGSEV. issue: The root cause: get_cancel_flag() is called from within propagation loops (mid-BCP, mid-equality-propagation, mid-atom-propagation). When it returns true there, the solver exits early and leaves the context in an intermediate state —
propagation queues partially processed, theory state potentially inconsistent with boolean state.
For the global cancel (m.limit().cancel()), this is harmless: the worker exits entirely and the context is destroyed. Intermediate state doesn't matter.
For a lease cancel, the context is reused — the worker gets a new cube and calls ctx->check() again on the same context object. Re-entering check() on a context interrupted mid-propagation causes it to access that corrupted intermediate
state → SIGSEGV.
The m_max_conflicts check is the only checkpoint that's safe for re-entry: it only fires post-conflict-resolution, pre-decision, when propagation queues are empty and theory state is consistent.
Fix: Remove m_lease_canceled from get_cancel_flag(). Keep it only at safe, between-phase checkpoints where the context is in a known-consistent state. The result is two safe checkpoints for m_lease_canceled: after each conflict (post-resolution, queues empty) and before each theory final check (not yet entered the theory). Neither interrupts the solver mid-mutation. The SIGSEGV should be
gone, and NIA performance should improve because long theory final checks (where NIA burns most time) are now preemptable before they start.
* fix new inconsistent theory bug: The problem is returning FC_GIVEUP from inside final_check() after some theories have already run final_check_eh() and pushed propagations into the queue. Those pending propagations reference context state that gets invalidated on the next check() call → SIGSEGV. The fix: check m_lease_canceled before entering final_check() in bounded_search(), never from inside it. That way the context is always in a clean pre-final-check state when we bail out. This is safe: decide() returned false (all variables assigned, no pending propagations), theories haven't been touched yet, context is in a fully consistent state. For NIA, this is still a meaningful win — we avoid entering expensive arithmetic final checks entirely when the lease is already canceled.
* remove second lease cancel check in smt_context, not sure it's safe. only check where we do the max conflicts check
* check epoch match in release_lease_unlocked
* restore exception handling logic to master branch
* restore reslimit cancels since the bug appears to be latent
---------
Co-authored-by: Ilana Shapiro <ilanashapiro@Ilanas-MacBook-Pro.local>
Co-authored-by: Ilana Shapiro <ilanashapiro@Mac.lan1>
|
||
|---|---|---|
| .github | ||
| a3 | ||
| agentics | ||
| cmake | ||
| codeql/custom_queries | ||
| contrib | ||
| doc | ||
| docker | ||
| examples | ||
| noarch | ||
| resources | ||
| scripts | ||
| src | ||
| .bazelrc | ||
| .clang-format | ||
| .dockerignore | ||
| .gitattributes | ||
| .gitignore | ||
| BUILD.bazel | ||
| build_z3.bat | ||
| CMakeLists.txt | ||
| configure | ||
| LICENSE.txt | ||
| MODULE.bazel | ||
| README-CMake.md | ||
| README.md | ||
| RELEASE_NOTES.md | ||
| Z3-AGENT.md | ||
| z3.pc.cmake.in | ||
| z3guide.jpeg | ||
Z3
Z3 is a theorem prover from Microsoft Research. It is licensed under the MIT license. Windows binary distributions include C++ runtime redistributables
If you are not familiar with Z3, you can start here.
Pre-built binaries for stable and nightly releases are available here.
Z3 can be built using Visual Studio, a Makefile, using CMake, using vcpkg, or using Bazel. It provides bindings for several programming languages.
See the release notes for notes on various stable releases of Z3.
Build status
Pull Request & Push Workflows
| WASM Build | Windows Build | CI | OCaml Binding |
|---|---|---|---|
 |
 |
 |
 |
Scheduled Workflows
| Open Bugs | Android Build | Pyodide Build | Nightly Build | Cross Build |
|---|---|---|---|---|
 |
 |
 |
 |
 |
| MSVC Static | MSVC Clang-CL | Build Z3 Cache | Code Coverage | Memory Safety | Mark PRs Ready |
|---|---|---|---|---|---|
 |
 |
 |
 |
 |
 |
Manual & Release Workflows
| Documentation | Release Build | WASM Release | NuGet Build |
|---|---|---|---|
 |
 |
 |
 |
Specialized Workflows
| Nightly Validation | Copilot Setup | Agentics Maintenance |
|---|---|---|
 |
 |
 |
Agentic Workflows
| A3 Python | API Coherence | Code Simplifier | Release Notes | Workflow Suggestion |
|---|---|---|---|---|
 |
 |
 |
 |
 |
| Academic Citation | Build Warning Fixer | Code Conventions | CSA Report | Issue Backlog |
|---|---|---|---|---|
 |
 |
 |
 |
 |
| Memory Safety Report | Ostrich Benchmark | QF-S Benchmark | Tactic-to-Simplifier | ZIPT Code Reviewer |
|---|---|---|---|---|
 |
 |
 |
 |
 |
Building Z3 on Windows using Visual Studio Command Prompt
For 32-bit builds, start with:
python scripts/mk_make.py
or instead, for a 64-bit build:
python scripts/mk_make.py -x
then run:
cd build
nmake
Z3 uses C++20. The recommended version of Visual Studio is therefore VS2019 or later.
Security Features (MSVC): When building with Visual Studio/MSVC, a couple of security features are enabled by default for Z3:
- Control Flow Guard (
/guard:cf) - enabled by default to detect attempts to compromise your code by preventing calls to locations other than function entry points, making it more difficult for attackers to execute arbitrary code through control flow redirection - Address Space Layout Randomization (
/DYNAMICBASE) - enabled by default for memory layout randomization, required by the/GUARD:CFlinker option - These can be disabled using
python scripts/mk_make.py --no-guardcf(Python build) orcmake -DZ3_ENABLE_CFG=OFF(CMake build) if needed
Building Z3 using make and GCC/Clang
Execute:
python scripts/mk_make.py
cd build
make
sudo make install
Note by default g++ is used as C++ compiler if it is available. If you
prefer to use Clang, change the mk_make.py invocation to:
CXX=clang++ CC=clang python scripts/mk_make.py
Note that Clang < 3.7 does not support OpenMP.
You can also build Z3 for Windows using Cygwin and the Mingw-w64 cross-compiler. In that case, make sure to use Cygwin's own Python and not some Windows installation of Python.
For a 64-bit build (from Cygwin64), configure Z3's sources with
CXX=x86_64-w64-mingw32-g++ CC=x86_64-w64-mingw32-gcc AR=x86_64-w64-mingw32-ar python scripts/mk_make.py
A 32-bit build should work similarly (but is untested); the same is true for 32/64 bit builds from within Cygwin32.
By default, it will install z3 executables at PREFIX/bin, libraries at
PREFIX/lib, and include files at PREFIX/include, where the PREFIX
installation prefix is inferred by the mk_make.py script. It is usually
/usr for most Linux distros, and /usr/local for FreeBSD and macOS. Use
the --prefix= command-line option to change the install prefix. For example:
python scripts/mk_make.py --prefix=/home/leo
cd build
make
make install
To uninstall Z3, use
sudo make uninstall
To clean Z3, you can delete the build directory and run the mk_make.py script again.
Building Z3 using CMake
Z3 has a build system using CMake. Read the README-CMake.md file for details. It is recommended for most build tasks, except for building OCaml bindings.
Building Z3 using vcpkg
vcpkg is a full platform package manager. To install Z3 with vcpkg, execute:
git clone https://github.com/microsoft/vcpkg.git
./bootstrap-vcpkg.bat # For powershell
./bootstrap-vcpkg.sh # For bash
./vcpkg install z3
Building Z3 using Bazel
Z3 can be built using Bazel. This is known to work on Ubuntu with Clang (but may work elsewhere with other compilers):
bazel build //...
Dependencies
Z3 itself has only few dependencies. It uses C++ runtime libraries, including pthreads for multi-threading. It is optionally possible to use GMP for multi-precision integers, but Z3 contains its own self-contained multi-precision functionality. Python is required to build Z3. Building Java, .NET, OCaml and Julia APIs requires installing relevant toolchains.
Z3 bindings
Z3 has bindings for various programming languages.
.NET
You can install a NuGet package for the latest release Z3 from nuget.org.
Use the --dotnet command line flag with mk_make.py to enable building these.
See examples/dotnet for examples.
C
These are always enabled.
See examples/c for examples.
C++
These are always enabled.
See examples/c++ for examples.
Java
Use the --java command line flag with mk_make.py to enable building these.
For IDE setup instructions (Eclipse, IntelliJ IDEA, Visual Studio Code) and troubleshooting, see the Java IDE Setup Guide.
See examples/java for examples.
Go
Use the --go command line flag with mk_make.py to enable building these. Note that Go bindings use CGO and require a Go toolchain (Go 1.20 or later) to build.
With CMake, use the -DZ3_BUILD_GO_BINDINGS=ON option.
See examples/go for examples and src/api/go/README.md for complete API documentation.
OCaml
Use the --ml command line flag with mk_make.py to enable building these.
See examples/ml for examples.
Python
You can install the Python wrapper for Z3 for the latest release from pypi using the command:
pip install z3-solver
Use the --python command line flag with mk_make.py to enable building these.
Note that it is required on certain platforms that the Python package directory
(site-packages on most distributions and dist-packages on Debian-based
distributions) live under the install prefix. If you use a non-standard prefix
you can use the --pypkgdir option to change the Python package directory
used for installation. For example:
python scripts/mk_make.py --prefix=/home/leo --python --pypkgdir=/home/leo/lib/python-2.7/site-packages
If you do need to install to a non-standard prefix, a better approach is to use
a Python virtual environment
and install Z3 there. Python packages also work for Python3.
Under Windows, recall to build inside the Visual C++ native command build environment.
Note that the build/python/z3 directory should be accessible from where Python is used with Z3
and it requires libz3.dll to be in the path.
virtualenv venv
source venv/bin/activate
python scripts/mk_make.py --python
cd build
make
make install
# You will find Z3 and the Python bindings installed in the virtual environment
venv/bin/z3 -h
...
python -c 'import z3; print(z3.get_version_string())'
...
See examples/python for examples.
Julia
The Julia package Z3.jl wraps the C API of Z3. A previous version of it wrapped the C++ API: Information about updating and building the Julia bindings can be found in src/api/julia.
WebAssembly / TypeScript / JavaScript
A WebAssembly build with associated TypeScript typings is published on npm as z3-solver. Information about building these bindings can be found in src/api/js.
Smalltalk (Pharo / Smalltalk/X)
Project MachineArithmetic provides a Smalltalk interface to Z3's C API. For more information, see MachineArithmetic/README.md.
AIX
Build settings for AIX are described here.
System Overview
Interfaces
-
Default input format is SMTLIB2
-
Other native foreign function interfaces:
-
Python API (also available in pydoc format)
-
C
-
OCaml
-
Smalltalk (supports Pharo and Smalltalk/X)
Power Tools
- The Axiom Profiler currently developed by ETH Zurich