Metadata-Version: 2.4
Name: fhy_core
Version: 0.0.6
Summary: Core utilities for the FhY compiler infrastructure.
Author-email: Christopher Priebe <cpriebe@ucsd.edu>
Maintainer-email: Christopher Priebe <cpriebe@ucsd.edu>
License: Copyright (c) 2024 FhY Developers
        Christopher Priebe <cpriebe@ucsd.edu>
        Hadi S Esmaeilzadeh <hadi@ucsd.edu>
        All Rights Reserved.
        
        Redistribution and use in source and binary forms, with or without modification, are
        permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this list of
        conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice, this list
        of conditions and the following disclaimer in the documentation and/or other materials
        provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors may be
        used to endorse or promote products derived from this software without specific prior
        written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY
        EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
        OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
        SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
        INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
        TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
        BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
        WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
        DAMAGE.
        
Project-URL: Homepage, https://github.com/actlab-fhy/FhY-core
Project-URL: Issues, https://github.com/actlab-fhy/FhY-core/issues
Keywords: Compiler
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: frozendict
Requires-Dist: networkx
Requires-Dist: sympy
Requires-Dist: z3-solver
Provides-Extra: dev
Requires-Dist: fhy_core[docs,lint,test,type]; extra == "dev"
Requires-Dist: tox; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Requires-Dist: pylint; extra == "lint"
Provides-Extra: type
Requires-Dist: mypy; extra == "type"
Dynamic: license-file

# *FhY* Core

*FhY* Core is a collection of utilities for *FhY* and other parts of the compiler.

| Utility                                  | Description                                                            |
| :--------------------------------------: | :--------------------------------------------------------------------- |
| Identifier                               | Unique naming class with a non-unique name hint and a unique ID.       |
| Error                                    | Custom error registration and core errors for the compiler.            |
| Expression                               | General expression represented as an AST with a parser and printer.    |
| Constraint                               | General logical constraint.                                            |
| Parameter                                | Real, integer, ordinal, categorical, and permutation parameters.       |
| Types                                    | Core type system for the compiler.                                     |
| Symbol Table                             | Nested symbol table.                                                   |
| Serializable Trait                       | `Serializable`/`WrappedFamilySerializable` with dict, JSON, and binary formats plus registered type IDs. |
| Compiler Traits - Identity               | `HasIdentifier` for stable object identity.                            |
| Compiler Traits - Provenance             | `HasProvenance` for source/origin tracking.                            |
| Compiler Traits - Type Carrier           | `HasType` for objects carrying an explicit type.                       |
| Compiler Traits - Operands               | `HasOperands` for operand-bearing operation/expression nodes.          |
| Compiler Traits - Results                | `HasResults` for multi-result operation-like nodes.                    |
| Compiler Traits - Freezing               | `Frozen`/`FrozenMixin` for runtime and dataclass immutability. |
| Compiler Traits - Equality               | `PartialEqual`/`Equal` for dataclass-aware equality semantics.         |
| Compiler Traits - Ordering               | `PartialOrderable`/`Orderable` for dataclass-aware ordering semantics. |
| Compiler Traits - Verification           | `Verifiable` + `VerificationError` for structural invariant checks.    |
| Compiler Traits - Folding                | `Foldable` for constant-fold-like evaluation hooks.                    |
| Compiler Traits - Canonicalization       | `Canonicalizable` for local canonical form rewrites.                   |
| Compiler Traits - Structural Equivalence | `StructuralEquivalence` for shape/value-level IR comparisons.          |
| _General Utility_ - Logging              | Core logging utilities for all compiler components.                    |
| _General Utility_ - Python 3.11 Enums    | String and integer enum types only introduced in Python 3.11           |
| _General Utility_ - Stack                | General stack utility that wraps `deque`.                              |
| _General Utility_ - POSET                | General partially ordered set utility represented as a directed graph. |
| _General Utility_ - Lattice              | General lattice (order theory) utility represented with a POSET.       |
| _General Utility_ - Dictionary Utilities | Additional dictionary helper functions.                                |


## Table of Contents
- [Installing *FhY* Core](#installing-fhy-core)
  - [Install *FhY* Core from PyPi](#install-fhy-core-from-pypi)
  - [Build *FhY* Core from Source Code](#build-fhy-core-from-source-code)
- [Contributing - For Developers](#contributing---for-developers)

### Install *FhY* Core from PyPi
**Coming Soon**

### Build *FhY* Core from Source Code

1. Clone the repository from GitHub.

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

2. Create and prepare a Python virtual environment.

    ```bash
    cd FhY-core
    python -m venv .venv
    source .venv/bin/activate
    python -m pip install -U pip
    pip install setuptools wheel
    ```

3. Install *FhY*.

    ```bash
    # Standard Installation
    pip install .

    # For contributors
    pip install ".[dev]"
    ```

## Contributing - For Developers
Want to start contributing the *FhY* Core? Please take a look at our
[contribution guide](CONTRIBUTING.md)
