thiran

KO | EN

gitlite — search

#nlp #web #openai #nodejs #reactjs #devops #java #swift #framework #cloud-native

(★ 9)

Experimental tensor-graph compiler with deterministic modules, compile-time functions, hybrid Region planning, and executable PyTorch artifacts.

File Explorer

ZIP Download

- - ci.yml
- Uninstall.cmake.in
- ADDING_AN_OPERATION.md
- ARCHITECTURE.md
- CLI.md
- FUNCTIONS.md
- ir.md
- MODULES.md
- optimizer.md
- PROJECT_STATUS.md
- scheduler.md
- TESTING.md
- cnn.th
- mlp.th
- simple.th
- transformer.th
- - CostModel.hpp
  - DependencyAnalysis.hpp
  - GraphStatistics.hpp
  - ResourceAnalysis.hpp
  - ResourceInfo.hpp
  - ShapeInference.hpp
  - TensorShape.hpp
- - BackendBuilder.hpp
  - BackendIR.hpp
  - FileEmitter.hpp
  - Kernel.hpp
  - KernelSignature.hpp
  - PythonExecutorEmitter.hpp
  - PyTorchEmitter.hpp
  - SignatureBuilder.hpp
  - SymbolBuilder.hpp
  - SymbolTable.hpp
  - TritonCodeGenerator.hpp
  - TritonEmitter.hpp
- - Config.hpp
  - Types.hpp
- - CompilationContext.hpp
  - CompilerPass.hpp
  - Pipeline.hpp
- - CommunicationEdge.hpp
  - CommunicationGraph.hpp
  - CommunicationPlanner.hpp
  - Partition.hpp
  - PartitionGraph.hpp
  - PartitionPlanner.hpp
- - Doctor.hpp
- - Ast.hpp
  - BuiltinOperations.hpp
  - CallGraph.hpp
  - FunctionInliner.hpp
  - Lexer.hpp
  - LinkedProgram.hpp
  - LoweringProvenance.hpp
  - ModuleLinker.hpp
  - Parser.hpp
  - SemanticAnalyzer.hpp
  - SourceLocation.hpp
  - SourceManager.hpp
  - Token.hpp
- - DataType.hpp
  - Edge.hpp
  - Graph.hpp
  - GraphWalker.hpp
  - Node.hpp
  - Operation.hpp
  - TensorType.hpp
- - CanonicalizationPass.hpp
  - ConstantFold.hpp
  - DCEPass.hpp
  - FusionPass.hpp
  - FusionRule.hpp
  - GraphVerifier.hpp
  - Pass.hpp
  - PassManager.hpp
  - Pattern.hpp
  - PatternMatcher.hpp
  - PatternNode.hpp
  - RemoveDoubleReluRule.hpp
  - RewriteEngine.hpp
  - RewriteRule.hpp
- - Lexer.hpp
  - Parser.hpp
  - Token.hpp
- - Region.hpp
  - RegionFormation.hpp
  - RegionGraph.hpp
  - RegionPlan.hpp
  - RegionPlanVerifier.hpp
  - RegionPythonEmitter.hpp
  - RegionVerifier.hpp
  - StrategyClassification.hpp
- - Executor.hpp
- - CostModel.hpp
  - Device.hpp
  - DevicePlanner.hpp
  - ExecutionGraph.hpp
  - ExecutionNode.hpp
  - ExecutionPlanner.hpp
  - Scheduler.hpp
- - Version.hpp.in
- - BackendPrinter.hpp
  - CodePrinter.hpp
  - CommunicationPrinter.hpp
  - ExecutionPrinter.hpp
  - FusionPrinter.hpp
  - GraphPrinter.hpp
  - GraphvizEmitter.hpp
  - Logger.hpp
  - PartitionPrinter.hpp
  - RegionExecutionDiagnosticPrinter.hpp
  - RegionPlanDiagnosticPrinter.hpp
  - RegionPlanPrinter.hpp
  - RegionPrinter.hpp
  - ResourcePrinter.hpp
  - SchedulePrinter.hpp
  - ShapePrinter.hpp
- install.sh
- validate.sh
- - CostModel.cpp
  - DependencyAnalysis.cpp
  - GraphStatistics.cpp
  - ResourceAnalysis.cpp
  - ResourceInfo.cpp
  - ShapeInference.cpp
  - TensorShape.cpp
- - BackendBuilder.cpp
  - BackendIR.cpp
  - FileEmitter.cpp
  - Kernel.cpp
  - PythonExecutorEmitter.cpp
  - PyTorchEmitter.cpp
  - SignatureBuilder.cpp
  - SymbolBuilder.cpp
  - SymbolTable.cpp
  - TritonCodeGenerator.cpp
  - TritonEmitter.cpp
- - CompilationContext.cpp
  - CompilerPass.cpp
  - Pipeline.cpp
- - CommunicationEdge.cpp
  - CommunicationGraph.cpp
  - CommunicationPlanner.cpp
  - Partition.cpp
  - PartitionGraph.cpp
  - PartitionPlanner.cpp
- - Doctor.cpp
- - BuiltinOperations.cpp
  - FunctionInliner.cpp
  - Lexer.cpp
  - ModuleLinker.cpp
  - Parser.cpp
  - SemanticAnalyzer.cpp
  - SourceManager.cpp
- - DataType.cpp
  - Edge.cpp
  - Graph.cpp
  - GraphWalker.cpp
  - Node.cpp
  - Operation.cpp
  - TensorType.cpp
- - CanonicalizationPass.cpp
  - ConstantFold.cpp
  - DCEPass.cpp
  - FusionPass.cpp
  - FusionRule.cpp
  - GraphVerifier.cpp
  - PassManager.cpp
  - Pattern.cpp
  - PatternMatcher.cpp
  - PatternNode.cpp
  - RemoveDoubleReluRule.cpp
  - RewriteEngine.cpp
- - Lexer.cpp
  - Parser.cpp
  - Token.cpp
- - Region.cpp
  - RegionFormation.cpp
  - RegionGraph.cpp
  - RegionPlan.cpp
  - RegionPlanVerifier.cpp
  - RegionPythonEmitter.cpp
  - RegionVerifier.cpp
  - StrategyClassification.cpp
- - Executor.cpp
- - Device.cpp
  - DevicePlanner.cpp
  - ExecutionGraph.cpp
  - ExecutionNode.cpp
  - ExecutionPlanner.cpp
  - Scheduler.cpp
- - BackendPrinter.cpp
  - CodePrinter.cpp
  - CommunicationPrinter.cpp
  - ExecutionPrinter.cpp
  - FusionPrinter.cpp
  - GraphPrinter.cpp
  - GraphvizEmitter.cpp
  - Logger.cpp
  - PartitionPrinter.cpp
  - RegionExecutionDiagnosticPrinter.cpp
  - RegionPlanDiagnosticPrinter.cpp
  - RegionPlanPrinter.cpp
  - RegionPrinter.cpp
  - ResourcePrinter.cpp
  - SchedulePrinter.cpp
  - ShapePrinter.cpp
- main.cpp
- - InstallationSupportTests.cpp
- - region_execution_multi_output_constant.th
  - region_runtime_dynamic_input.th
- - FunctionLoweringTests.cpp
  - FunctionSemanticTests.cpp
  - ModuleLinkerTests.cpp
  - SourceManagerTests.cpp
- - FunctionIntegrationTests.cmake
  - InstallationCliTests.cmake
  - ModuleCliTests.cmake
  - RegionExecutionTests.cmake
  - RegionPlanCliTests.cmake
  - RegionRuntimeCliTests.cmake
- - RegionFormationTests.cpp
  - RegionIRTests.cpp
  - RegionPlanCliSupportTests.cpp
  - RegionPlanTests.cpp
  - RegionPythonEmitterTests.cpp
  - RegionPythonRuntimeTests.cpp
  - StrategyClassificationTests.cpp
.gitignore
CMakeLists.txt
CMakePresets.json
CONTRIBUTING.md
generated.py
graph.dot
graph.png
LICENSE
README.md
requirements-test.txt
VERSION

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Thiran is a C++20 research compiler prototype for a small tensor-dataflow language with deterministic Region planning and a PyTorch execution path.

## Current status

Thiran parses and links single-file or explicitly imported `.th` modules into one Graph IR, verifies and prepares that Graph, classifies nodes, forms connected Regions, builds an immutable `RegionPlan`, and can emit a Region-controlled Python artifact. The artifact executes one Python function per Region and passes boundary tensors explicitly. All `AOT`, `JIT`, and `FALLBACK` Regions currently use PyTorch; the strategy labels do not select native implementations.

## What is implemented

- Source locations, explicit modules/imports/exports, top-level tensor functions, deterministic compile-time Graph inlining, Graph IR ownership, verification, optimization, and shape inference.
- Deterministic node strategy classification and connected Region formation.
- Immutable RegionPlan construction, verification, inspection, and text emission.
- Region-controlled Python source emission with explicit Region inputs and outputs.
- Import-safe and directly executable tensor-bundle artifacts.
- Restricted `torch.load(..., weights_only=True)`, input shape validation, and atomic output writes.
- Deterministic diagnostics and numerical equivalence tests against the accepted whole-Graph PyTorch path.

## What is not implemented

Native AOT and JIT compilation, specialization and artifact caches, adaptive dispatch, working Triton execution, distributed execution, and demonstrated performance improvements are not implemented. Scheduler, partition, communication, BackendIR, Executor, and Triton structures exist, but they do not make Region strategies execute through distinct native backends.

## Architecture overview

```text
source
  -> Graph IR
  -> preparation and shape analysis
  -> strategy classification
  -> connected Regions
  -> immutable RegionPlan
  -> Region-controlled Python artifact
  -> PyTorch execution
```

The existing normal compiler path additionally emits `graph.dot` and the whole-Graph `generated.py`. See [Architecture](docs/ARCHITECTURE.md).

## Prerequisites

The validated contributor environment is Linux or WSL with:

- CMake 3.20 or newer;
- Ninja;
- a C++20 compiler (GCC 13 is locally validated);
- Git;
- for `BUILD_TESTING=ON`, Python 3 and a PyTorch installation supporting `torch.load(..., weights_only=True)`.

`BUILD_TESTING=OFF` builds the compiler without selecting Python or importing Torch. Test builds prefer `THIRAN_PYTHON_EXECUTABLE`, then `.venv/bin/python`, then a Python 3 interpreter found by CMake. A `.venv` is convenient, not mandatory.

For a test environment:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-test.txt
```

## Quick build

```bash
cmake --preset debug
cmake --build --preset debug
```

The Debug executable is `build/debug/Thiran`.

## Install locally

Linux/WSL source installation uses no sudo and installs only lowercase `thiran`:

```bash
./scripts/install.sh --prefix "$HOME/.local"
"$HOME/.local/bin/thiran" --version
"$HOME/.local/bin/thiran" doctor
```

The default prefix is `$HOME/.local`. Add its `bin` directory to `PATH` yourself if needed. To uninstall the most recent installation made from `build/install`:

```bash
cmake --build build/install --target uninstall
```

No remote installer or package-manager distribution exists.

## Run all tests

```bash
ctest --preset debug --output-on-failure
```

Exactly fifteen CTest registrations are expected. See [Testing](docs/TESTING.md).

## Inspect a plan

```bash
./build/debug/Thiran --plan examples/cnn.th
```

## Emit a plan artifact

```bash
./build/debug/Thiran --emit-plan examples/cnn.th /tmp/cnn-region-plan.txt
```

## Emit a Region executor

```bash
./build/debug/Thiran --emit-region-executor examples/cnn.th /tmp/cnn-executor.py
```

## Describe a Region executor

```bash
.venv/bin/python /tmp/cnn-executor.py --describe
```

Use the Python interpreter selected for the test build if it is not `.venv/bin/python`.

## Execute a Region executor

Create a deterministic input bundle:

```bash
.venv/bin/python -c "import torch; torch.save({'Image': torch.arange(64, dtype=torch.float32).reshape(1,1,8,8), 'Filter': torch.full((2,1,3,3), 0.25), 'Classifier': torch.arange(72, dtype=torch.float32).reshape(18,4) / 72}, '/tmp/cnn-inputs.pt')"
```

Run and safely load the result:

```bash
.venv/bin/python /tmp/cnn-executor.py --run /tmp/cnn-inputs.pt /tmp/cnn-outputs.pt
.venv/bin/python -c "import torch; outputs=torch.load('/tmp/cnn-outputs.pt', map_location='cpu', weights_only=True); print(tuple(outputs))"
```

The output key is `O`. The runtime rejects malformed bundles and never falls back to unrestricted loading.

## Repository layout

- `include/`, `src/`: compiler and Region runtime source.
- `tests/region/`: zero-dependency C++ test harnesses.
- `tests/integration/`: CMake-driven CLI and numerical tests.
- `tests/fixtures/`: source fixtures.
- `examples/`: sample `.th` programs.
- `docs/`: architecture, CLI, testing, operation, and status guides.
- `docs/FUNCTIONS.md`: immutable tensor-function syntax and deterministic inlining rules.
- `scripts/validate.sh`: local contributor validation.
- `.github/workflows/ci.yml`: continuous-integration mirror.

## Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [CLI reference](docs/CLI.md)
- [Testing and validation](docs/TESTING.md)
- [Adding an operation](docs/ADDING_AN_OPERATION.md)
- [Project status](docs/PROJECT_STATUS.md)
- [Modules](docs/MODULES.md)

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing compiler semantics.

## Known limitations

The source language and operation set are limited. Current Region execution is correctness-oriented PyTorch, not native AOT/JIT execution. No performance or recompilation-locality result is established. Linux/WSL is the validated environment.

## License status

The repository contains an empty `LICENSE` file; redistribution and reuse terms have not yet been selected. Selecting a license is an owner decision and remains a release blocker.

thiran

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README