py-tetrad: Instructions file for Claude Code

CLAUDE.md — py-tetrad project guidance

This project accesses the Tetrad causal discovery library (Java) from Python via py-tetrad and JPype. Follow the rules below when writing or modifying code.

Environment

• Python 3.14, JPype1 (pip install JPype1), pandas, numpy.
• JDK 21 (Tetrad requires 21+). JAVA_HOME must point to it.
• Tetrad is provided by the jar pytetrad/resources/tetrad-current.jar (or a project-local copy of it). This jar is the latest published beta built from the development branch of https://github.com/cmu-phil/tetrad. The jar changes over time.

Source of truth for the Tetrad API

• The Tetrad API you are calling is defined by the development branch of https://github.com/cmu-phil/tetrad (current working branches may exist, e.g. joe-work-2026-8-4, but code here should target development).
• Do NOT rely on memorized Tetrad class names, packages, or signatures — they change between versions. Before using any Tetrad class or method, verify it against the development-branch source (fetch the file from GitHub or read a local clone) or the published Javadocs.
• Key packages: edu.cmu.tetrad.data, edu.cmu.tetrad.graph, edu.cmu.tetrad.search, edu.cmu.tetrad.search.score, edu.cmu.tetrad.search.test, edu.cmu.tetrad.algcomparison.
• Parameter meanings and defaults are documented in the Tetrad manual: https://tetrad-manual.readthedocs.io/en/latest/

JPype rules (important)

1. Start the JVM ONCE, before importing any Java package, e.g.:

   import jpype
   import jpype.imports
   
   if not jpype.isJVMStarted():
       jpype.startJVM(classpath=["pytetrad/resources/tetrad-current.jar"])
   
   import edu.cmu.tetrad.search as ts
   

2. Never call jpype.startJVM twice in one process; guard with jpype.isJVMStarted(). Design scripts so all JVM work happens in a single process.

3. Give the JVM memory if needed: jpype.startJVM("-Xmx4g", classpath=[...]).

4. Convert Java values coming back to Python explicitly (str(...), int(...), list comprehension over Java lists) before handing them to pandas/numpy.