FhY Core

FhY Core provides the shared foundation used by the FhY compiler and its companion tooling: identifier and symbol management, an extensible expression and type system, parameter and constraint modeling, pass/analysis/validation infrastructure, serialization, reusable compiler traits, and supporting data structures and utilities. Each utility is independently usable and designed to be extended downstream.

Utility	Description
Identifier	Globally unique identity (`Identifier`) pairing a human-readable name hint with a process-unique ID for stable referencing of compiler entities.
Error	Base `FhYError` hierarchy and a registration mechanism for downstream packages to declare their own typed compiler errors.
Expression	Pure-expression IR (literals, identifiers, unary/binary/ternary/call nodes) with a pretty printer, sort-aware type checker, sympy and z3 lowering, and a process-wide function registry (`RegisteredFunction` for expression bodies, `NativeFunction` for Python-backed math, `NativeConstant` for named values like `pi`/`e`) driven by a `FunctionSort` signature system (`BOOL`/`NAT`/`INT`/`REAL`). `BUILTIN_FUNCTIONS` and `BUILTIN_CONSTANTS` seed the standard transcendental, trigonometric, rounding, and activation helpers. `FunctionInliner` and `ExpressionEvaluator` (both built on `RewritablePass[Expression]`) compose into the rewriter pipeline.
Expression Pattern Matching	`Pattern` algebra over the expression IR (`WildcardPattern`, `CapturePattern`, `LiteralPattern`, `IdentifierPattern`, `UnaryExpressionPattern`/`BinaryExpressionPattern`/`TernaryExpressionPattern`/`CallExpressionPattern`, `PredicatePattern`, `AlternativesPattern`) with `match_pattern`/`does_pattern_match` returning `MatchBindings` keyed by capture name. `RewriteRule` pairs a pattern with a rewrite function, and `apply_rewrite_rule`/`apply_rewrite_rules`/`RewriteRuleApplier` drive rule application across an expression tree.
Constraint	Logical constraint objects built over expressions, suitable for parameter bounds, guards, and solver-facing predicates.
Parameter	Real, integer, ordinal, categorical, and permutation parameter types with constraint attachment and sampling/validation hooks for tuning and search.
Types	Extensible type system with open dispatchers for binding, substitution, unification, and structural equivalence; expression type checking layered on top.
Symbol Table	Lexically nested symbol table with scope push/pop, shadowing rules, and lookup utilities for compiler frontends.
Pass Infrastructure	`CompilerPass`, `VisitablePass`, `RewritablePass`, `AnalysisVisitablePass`, and `register_pass` for authoring IR passes, with `PassInfo`/`PassResult`/`PreservedAnalyses` metadata and `PassRegistrationError`/`PassValidationError`/`PassExecutionError` for typed failures.
Pass Manager	`PassManager` sequences transformations and returns `PassManagerResult`/`PassRunRecord`; `FixpointPassGroup` drives until-fixpoint iteration with `FixpointGroupRecord`/`FixpointIterationRecord` traces.
Analysis Manager	`Analysis`/`AnalysisVisitablePass` with `AnalysisManager` for caching analysis results and invalidating them across pass runs.
Validation Manager	`ValidationManager` runs every validator against the IR (collect-all, never fail-fast) and aggregates their diagnostics into a single report.
Verification Registry	`VerificationRegistry` + `@register_verification` declare per-class verification passes (walking MRO); `run_verification` and `VerificationAnalysis` execute them, backing the default `VerifiableMixin.verify`.
Diagnostic	`Diagnostic`/`DiagnosticLevel` and `Note` (tagged by an open `NoteKind` registry of message roles) for structured compiler messages, plus `ValidationReport` for aggregating them and `ValidationFailedError` (raised by `ValidationReport.raise_if_failed`) for surfacing ERROR diagnostics as exceptions.
Serializable Trait	`Serializable`/`WrappedFamilySerializable` with dict, JSON, and binary formats plus registered type IDs for round-tripping IR and metadata.
Value Domain	`ValueDomain` open registry classifying the kind of value an IR operation handles (e.g., `DATA_DOMAIN`, `ADDRESS_DOMAIN`), with optional parent hierarchies.
Op Attribute	`OpAttribute` open registry of semantic tags attachable to compiler operations (`COMMUTATIVE`, `ASSOCIATIVE`, `PURE`, `ELEMENTWISE`).
Compiler Traits - Identity	`HasIdentifier` mixin giving an object a stable `Identifier` for referencing across passes.
Compiler Traits - Provenance	`HasProvenance` mixin attaching source location/origin metadata for diagnostics and traceability.
Compiler Traits - Type Carrier	`HasType` mixin for nodes that carry an explicit, queryable type.
Compiler Traits - Operands	`HasOperands` mixin exposing a uniform operand interface for operation/expression nodes.
Compiler Traits - Results	`HasResults` mixin for operation-like nodes producing one or more named results.
Compiler Traits - Rewritable	`Rewritable` protocol and `RewritableMixin` for IR nodes that can be reconstructed from a new child sequence; the inverse of `Visitable.get_visit_children`, used by generic bottom-up rewriters such as `RewritablePass`.
Compiler Traits - Freezing	`Frozen` protocol and `FrozenMixin` for runtime and dataclass immutability, with optional auto-freeze-on-init and `FrozenMutationError`/`FrozenValidationError` for mutation and verification failures.
Compiler Traits - Equality	`PartialEqual`/`Equal` for dataclass-aware structural equality.
Compiler Traits - Ordering	`PartialOrderable`/`Orderable` for dataclass-aware ordering and comparison.
Compiler Traits - Verification	`Verifiable` protocol and `VerifiableMixin` for self-verifying IR nodes; `verify()` returns the aggregated diagnostic report from passes registered via `register_verification`. `VerificationError` remains for fail-fast structural-correctness helpers.
Compiler Traits - Canonicalization	`Canonicalizable` hook for local rewrites into a canonical form.
Compiler Traits - Structural Equivalence	`StructuralEquivalence` for shape- and value-level comparisons between IR fragments.
Compiler Traits - Alpha Equivalence	`AlphaEquivalence` protocol and `AlphaEquivalenceMixin` for comparing IR fragments up to consistent identifier renaming, driven by an injective `AlphaRenaming` map; `is_identifier_mapping_alpha_equivalent_under` is the per-`Identifier` building block used by expression nodes.
Compiler Traits - Derived Equivalence	`DerivedEquivalenceMixin` derives both structural and alpha equivalence from a dataclass's fields, with the `compared_as_value`/`compared_as_reference`/`compared_as_binder`/`compared_with`/`excluded_from_equivalence` field markers to control how each field participates.
Compiler Traits - Binding	`BinderMixin` with the `Term`/`HasFreeIdentifiers` protocols for IR nodes that introduce a binding scope; derives alpha-equivalence, free-identifier computation, and capture-avoiding substitution from a few per-node hooks.
Compiler Traits - Interned	`Interned` mixin for components with hash-consed, deduplicated instances.
Data Structure - Lattice	Order-theoretic lattice built on a POSET, with join/meet operations for dataflow-style analyses.
General Utility - Logging	Centralized logging configuration and helpers shared by all compiler components.
General Utility - Python 3.11 Enums	Backports of `StrEnum` and `IntEnum` semantics introduced in Python 3.11.
General Utility - Stack	Lightweight stack wrapping `collections.deque` with a clearer interface.
General Utility - Scope	`Scope` stack of LIFO name-binding frames with innermost-first shadowing lookup and a context manager for scoped push/pop; generalizes the scoping used by `SymbolTable`.
General Utility - POSET	Partially ordered set represented as a directed graph, with reachability and transitive-closure queries.
General Utility - Dictionary Utilities	Helper functions for common dictionary manipulations not covered by the standard library.
General Utility - Numeric Predicates	`is_strict_int` rejects `bool` so contexts requiring a strict integer do not silently accept `True`/`False`.

Installation

Install from PyPI

pip install fhy_core

Build from Source

This project uses uv for environment and dependency management. Install uv, then:

Clone the repository.

git clone https://github.com/actlab-fhy/FhY-core.git
cd FhY-core

Create the environment and install the package.
```
# Runtime dependencies only
uv sync --no-default-groups

# For contributors (default dev group: test, lint, type, property, nox, pre-commit)
uv sync
```
uv sync creates .venv and installs fhy_core in editable mode. Prefix commands with uv run (e.g. uv run python) or activate the environment with source .venv/bin/activate.

Contributing

Interested in contributing to FhY Core? See the contribution guide.

Metadata

Release files for fhy_core 0.1.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fhy_core 0.1.8
File	Size	Uploaded
fhy_core-0.1.8.tar.gz	181.0 kB	Jul 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for fhy_core 0.1.8
File	Interpreter	ABI	Platform	Reset
fhy_core-0.1.8-py3-none-any.whl 217.0 kB Jul 3, 2026	Python 3	none	any	Details

Total release size: 398.0 kB

Release files / fhy_core-0.1.8.tar.gz

Download URL	fhy_core-0.1.8.tar.gz
Size	181.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`5ee6058a96c50e39fa4b1d6954739d3c7aabe690c82da692458b9eca413ff1e4`
BLAKE2b-256 checksum How to use checksums	`fc09527ffd455be5d1ee79174d4d3e9a3457bb44d4a279773cc54d89e5034920`
Upload date	Jul 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fhy_core-0.1.8-py3-none-any.whl

Download URL	fhy_core-0.1.8-py3-none-any.whl
Size	217.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5fe6c74c882a3129360d056bbc75ba23106db2d907b0968f4981ba6fe8e10480`
BLAKE2b-256 checksum How to use checksums	`6dc840983b28f2781db8a9609e3e29d7fb9b01d0d46bce1217cf23fd53704c11`
Upload date	Jul 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`