CausalEngine installation

1. Install the tested revision

Use Python 3.11 for the verified path below. Package metadata allows Python 3.11 or later, but this pass tested only 3.11.14 on macOS 15.6.1, Apple Silicon. Linux/Windows and newer Python versions were not tested in this pass.

Prerequisites are Git, Python with venv/pip, repository access through your normal Git credentials, and internet access for the initial dependency download. A virtual environment (venv) keeps this project’s Python packages separate from other projects. From a directory where you keep code, run these commands in a macOS/Linux terminal:

git clone https://github.com/CausalDataScience/CausalEngine.git
cd CausalEngine
git checkout --detach bd14e4dc638982bf86fb0ba86625ab97bb2dda98
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install .
python -c "import sys, causalengine; print(sys.executable); print(causalengine.__version__)"
python -m causalengine.demo

Expected package version: 0.1.0a13. The demo prints two JSON records, scalar and cluster, with identification and estimation both ACCEPT. Its current fixtures select BD. Estimates are compared with independent intervention samples; they need not equal the sample reference exactly.

The full commit is the implementation runtime pin. Keep an experiment’s package revision fixed when main advances. This documentation refresh and the new maintained workflow may be supplied from a later documentation revision; its standalone Python block runs against the pinned installed runtime. Code and documentation provenance are intentionally identified separately.

Use an existing project environment instead of creating .venv if that project already has its own environment and dependency policy. On Windows, the analogous commands are py -3.11 -m venv .venv and .\.venv\Scripts\Activate.ps1 in PowerShell; that platform path has not been execution-tested here.

Use regular installation for the pinned consumer revision above. The following development instructions apply to the consolidated checkout layout, not to older source pins whose build rejected editable installation. Runtime source is directly under src/causalengine/; regular and editable builds use the same module files. For development, use python -m pip install --no-deps --no-build-isolation -e . in an environment with the declared dependencies already installed, or set PYTHONPATH=src for source-only checks. No external paper checkout, Graphviz executable, GPU, or plotting extra is required for the default demo and sampling example.

2. Check the public API without downloading data

Run this Python code with the same active environment. mechanism="mixed" selects synthetic covariates, so this example does not contact OpenML:

from causalengine import CSCM, CovariateOptions, OutcomeOptions

task = CSCM(d_X=5, task_seed=42,
    covariates=CovariateOptions(mechanism="mixed"),
    outcome=OutcomeOptions(family="gaussian"))
observed, truth = task.sample(32, data_seed=7)
print(observed["X"].shape, observed["A"].shape, observed["Y"].shape)
assert "U" not in observed
# (32, 5) (32,) (32,)

CSCM is the hidden-common-cause task generator. Observations and generator truth are separate outputs; truth must not be passed as observed model inputs. Successful sampling does not assert that every query on this graph is identifiable. For numerical estimation, follow the identified-mean example.

To check the installed package from a directory outside the source checkout:

python -m unittest discover -s /absolute/path/to/CausalEngine/tests -p 'test_public_api.py' -q
python -m unittest discover -s /absolute/path/to/CausalEngine/tests -p 'test_cscm.py' -q

Replace /absolute/path/to/CausalEngine with your clone’s actual path. The tests import the installed package. Expected results at the pin are 8 tests and 13 tests, respectively, both OK.

3. Use the package from another project

Activate that project’s environment, then install the same pinned source:

python -m pip install "causalengine @ git+https://github.com/CausalDataScience/CausalEngine.git@bd14e4dc638982bf86fb0ba86625ab97bb2dda98"
python -m causalengine.demo

The same direct-URL line can go in the consuming project’s requirements.txt:

causalengine @ git+https://github.com/CausalDataScience/CausalEngine.git@bd14e4dc638982bf86fb0ba86625ab97bb2dda98

Git access must work for that user. Do not embed tokens/passwords in URLs, notebooks, or requirements files. The syntax follows pip’s VCS support. The source pin fixes CausalEngine code, while transitive dependency versions can still differ. Record the project’s dependency lock or installed package versions together with the source commit. 0.1.0a9 alone is not a unique artifact identifier. Updating the source checkout does not update an installed package; reinstall the chosen revision and rerun the smoke checks.

4. Optional plots and wheel delivery

The package’s dependencies are declared in pyproject.toml, including NumPy, pandas, NetworkX, SciPy, scikit-learn, and XGBoost. Let normal package installation resolve them; the historical root requirements.txt is not the installation contract for this package.

For plotting, run this from the pinned clone with its environment active:

python -m pip install '.[plot]'

This adds matplotlib, PyVis, and Plotly. Basic graph queries and sampling do not need them. The graph drawing functions use NetworkX layouts/PyVis, not Graphviz.

If the lab supplies an approved wheel, install its exact path instead of cloning:

python -m pip install /path/to/causalengine-0.1.0a9-py3-none-any.whl
python -m causalengine.demo

That wheel contains CausalEngine, not its numerical dependencies. The command can still download dependencies. A truly offline machine needs an already compatible environment or a lab-provided wheelhouse containing all dependencies for its OS/Python. Given such a complete wheelhouse, use python -m pip install --no-index --find-links /path/to/wheelhouse /path/to/causalengine-0.1.0a9-py3-none-any.whl. Record the supplied wheel’s SHA-256 and source commit. A wheel built for this validation is a temporary local artifact, not a promised lab download endpoint.

5. Troubleshooting

If installation still fails, send the lab maintainer the OS/architecture, python --version, interpreter path, source pin, python -m pip show causalengine, and the relevant traceback. Remove credentials from shared logs.

6. Validation records

The a13 implementation at bd14e4dc was built and installed as a regular wheel in an isolated temporary target with existing dependencies. Its final validation ran 38 installed contracts and 22 graph-engine regressions: 60 passed, zero skips. Seven graph-free/effect guide blocks passed. All 36 wheel payload files matched installed bytes. No fresh dependency resolution or additional OS verification was performed; see the current record.

Historical a9 installation validation

The following records preserve the earlier a9 install check; its source pin and version differ from the current a13 instructions above.

On 2026-10-25, the tracked source at 8e794ec6ff6b41ec6a3f72054b0a2b48d7ad7ec2 was copied to an isolated /tmp staging directory. A regular wheel build succeeded using existing setuptools 82.0.1. The wheel metadata declared 0.1.0a9, Python >=3.11, and contained the required bundled engine and covariate data files.

The wheel itself was installed into a new temporary target with uv pip install --no-deps --offline, reusing an existing Python 3.11.14 environment’s dependencies on macOS 15.6.1 arm64. Public examples and tests ran outside the checkout, with these results:

This verifies the regular build/installed package with that dependency runtime. It does not reproduce fresh-venv dependency resolution or establish Linux/Windows compatibility. No project dependencies, system libraries, GitHub permissions, or account settings were changed.

For API behavior and current implementation limits, see the usage guide and implementation Wiki.