Metadata-Version: 2.4
Name: emmiai-noether
Version: 2.0.0
Summary: Noether: A PyTorch-based Framework for Engineering AI
Author-email: Emmi AI <contact@emmi.ai>
License-Expression: LicenseRef-ENPL
Project-URL: Source, https://github.com/Emmi-AI/noether
Project-URL: Docs, https://noether-docs.emmi.ai/
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: setuptools
Requires-Dist: wheel
Requires-Dist: loguru>=0.7.3
Requires-Dist: einops>=0.8.1
Requires-Dist: hydra-core>=1.3.2
Requires-Dist: numpy==2.3.1
Requires-Dist: torch==2.8.0
Requires-Dist: pandas>=2.3.3
Requires-Dist: aistore>=1.13.5
Requires-Dist: pyvista>=0.44.2
Requires-Dist: rtree>=1.4.0
Requires-Dist: trimesh>=4.6.6
Requires-Dist: boto3>=1.40.4
Requires-Dist: huggingface-hub>=0.34.3
Requires-Dist: typer>=0.16.0
Requires-Dist: fsspec>=2025.5.1
Requires-Dist: psutil>=5.9.0
Dynamic: license-file

<div align="center">

![noether-framework-logo](https://raw.githubusercontent.com/Emmi-AI/noether/main/docs/source/_static/noether-framework-logo.svg)

# Noether Framework

[![Docs - noether-docs.emmi.ai](https://img.shields.io/static/v1?label=Docs&message=noether-docs.emmi.ai&color=2ea44f&logo=gitbook)](https://noether-docs.emmi.ai)
[![License: ENPL](https://img.shields.io/badge/License-ENPL-orange.svg)](https://github.com/Emmi-AI/noether/blob/main/LICENSE.txt)
[![Static Badge](https://img.shields.io/badge/Walkthrough-Tutorial-DD537C)](https://github.com/Emmi-AI/noether/blob/main/tutorial/README.MD)

[![Tests](https://github.com/Emmi-AI/noether/actions/workflows/run-tests.yml/badge.svg)](https://github.com/Emmi-AI/noether/actions/workflows/run-tests.yml)

</div>

<div>
<strong>Noether</strong> is Emmi AI’s <strong>open software framework for Engineering AI</strong>. Built on 
<strong>transformer building blocks</strong>, it delivers the full engineering stack, allowing teams to build, 
train, and operate industrial simulation models across engineering verticals, eliminating the need for component 
re-engineering or an in-house deep learning team.
</div>

## Key Features

- **Modular Transformer Architecture:** Built on building blocks optimized for physical systems.
- **Hardware Agnostic:** Seamless execution across CPU, MPS (Apple Silicon), and NVIDIA GPUs.
- **Industrial Grade:** Designed for high-fidelity industrial simulations and engineering verticals.
- **Ready for Scale:** Built-in support for Multi-GPU and SLURM cluster environments.

---

# Table of contents

- [Installation](#installation)
  - [Pre-requisites](#pre-requisites)
  - [Working with the source code](#working-with-the-source-code)
    - [How to clean up and do a fresh installation](#how-to-clean-up-and-do-a-fresh-installation)
  - [Working with pre-built packages](#working-with-pre-built-packages)
- [Quickstart](#quickstart)
- [Performance Benchmarks](#performance-benchmarks)
- [Contributing](#contributing)
  - [Guidelines](#guidelines)
  - [Third-party contributors](#third-party-contributors)
  - [Configuring IDEs](#configuring-ides)
- [Supported systems](#supported-systems)
- [Licensing](#licensing)
- [Endorsements](#endorsed-by)
- [Citing](#citing)

---
# Installation

It is possible to use the framework either from source or from the pre-built packages.

## Pre-requisites

- install [uv](https://docs.astral.sh/uv/getting-started/installation/) as the package manager on your system
- clone the repo into your desired folder, if you wish to work with the code: `git clone https://github.com/Emmi-AI/noether.git`

## Working with pre-built packages

Installable package is available via `pip` and can be installed as:

```bash
pip install emmiai-noether
```

or if you use `uv`:

```bash
uv pip add emmiai-noether
```

## Working with the source code

If you prefer to work with the source code directly without installing a prebuilt package.

<details>
  <summary>Linux and CUDA</summary>
  
  If you are running on NVIDIA GPUs or need custom CUDA paths, you must configure your environment variables first. 
  Please follow our [Advanced Linux Setup Guide](https://noether-docs.emmi.ai/guides/linux_cuda_setup.html) before 
   running the command below.
  
</details>

Create a fresh virtual environment and synchronize the core dependencies after cloning the repo:

```console
uv venv && source .venv/bin/activate
uv sync
```

**Note:** Initial installation may take several minutes. Duration depends on your hardware and network speed.

Validate your installation by simply running the tests (if something fails with module import errors it means that the 
installation was incomplete):
```console
pytest -q tests/
```
if the tests are passed (warnings are okay to be logged) then you're all set and ready to go!

### Install via GitHub

You can install Noether directly from GitHub as well:

```bash
uv add "emmiai-noether @ git+https://github.com/Emmi-AI/noether.git"
```

This way you will stay always up-to-date with the recent updates and don't wait for the built packages being released.

### How to clean up and do a fresh installation

You might be in a situation when your venv won't be configured as intended anymore, to fix this:

- Deactivate existing environment in your terminal by running: `deactivate`
- Remove existing `.venv` (optionally add `uv.lock`): `rm -rf .venv uv.lock`
- [Optional] Clean uv cache: `uv cache clean`
- Create a new venv and activate it: `uv venv && source .venv/bin/activate`
- [Optional] If deleted, generate a new `uv.lock` file: `uv lock`
- [Optional] If contributor: `pre-commit install`

---
# Quickstart

## Scaffold a New Project

You can get started with scaffolding a project directly with `uvx`:

```console
uvx --from emmiai-noether noether-init my_project
cd my_project
uv run noether-train --hp my_project/configs/base_experiment.yaml
```

Or if you have `emmiai-noether` already installed:

```console
uv run noether-init my_project
cd my_project
uv run noether-train --hp my_project/configs/base_experiment.yaml
```

See the [scaffolding tutorial](https://noether-docs.emmi.ai/tutorials/scaffolding_a_new_project.html) for all options and the generated project structure.

## Run the Tutorial Example

You can also run a training job immediately using the [tutorial](./tutorial/README.MD) configuration:

```console
uv run noether-train --hp tutorial/configs/train_shapenet.yaml \
    +experiment/shapenet=upt \
    dataset_root=./data \
    +accelerator=mps \
```

Learn more about different hardware support [here](https://noether-docs.emmi.ai/guides/hardware_setup.html).

---
# Performance Benchmarks

The following benchmarks demonstrate **Noether**'s acceleration compatibility over different hardware using 
the `ShapeNet-Car` dataset and the `AB-UPT` model. 

> [!NOTE]
> All benchmarks were conducted using **FP32 precision** to establish a baseline for raw computational performance.

| **Hardware**                 | **Config** | **Precision** | **Time** | **Speedup** |
|:-----------------------------|:-----------|:--------------|:---------|:------------|
| **MacBook Pro M3 Max**       | 1x MPS     | FP32          | 135m     | 1.0x        |
| **RTX Pro 4500 (Blackwell)** | 1x GPU     | FP32          | 26m      | 5.2x        |
| **RTX Pro 4500 (Blackwell)** | 2x GPU     | FP32          | 8m       | 16.8x       |
| **NVIDIA H100**              | 1x GPU     | FP32          | 5.7m     | 23.6x       |

---
# Contributing

## Guidelines

We follow these standards:

- Use typed coding in Python.
- Write documentation to new features and modules:
  - In case of larger modules make sure to update the documentation that is not autogenerated under the `docs/`.
  - For smaller features writing a clear API documentation is enough and required.
- Before committing your changes:
  - Run tests via `pytest -q tests/`.
  - Ensure that [pre-commit hooks](#pre-commit-hooks) are not disabled and are runnable at every commit.
    We are using `ruff` as a linter and formatter as well as `mypy` for type checking.
    Their configuration is defined in the project's root [pyproject.toml](pyproject.toml).
- Creating pull requests (PRs) is a mandatory step for any incoming changes that will end up on the `main` branch.
  - For a PR to be merged at least one core maintainer must give their approval.
  - All test must be green

## Pre-commit Hooks

To install pre-commit execute:
```console
pre-commit install
```
To run the pre-commit configuration on all files, you can use:
```console
pre-commit run --all-files
```
To run the pre-commit configuration on specific files use:
```console
pre-commit run --files /your/file/path1.py /your/file/path2.py
```

## Third-party contributors

In case of bugs use a corresponding template to create an issue.

In case of feature requests you can submit a PR with clear description of the proposed feature. In that case it must 
follow the [guidelines](#guidelines), or file a feature request as an issue. In that case, we will consider adding it to our 
backlog.

## Configuring IDEs

### Pycharm

- Mark `src/` directory as `Sources Root` (right mouse button click on the folder -> `Mark Directory as`)
- Settings -> Editor -> Code Style -> Python -> Tabs and Indents -> change `Continuation indent` from 8 to 4.
- Settings -> Editor -> Code Style -> Python -> Spaces -> Around Operators -> `Power operator (**)`

---
# Supported systems
Worth noting that we work with macOS and Linux environments thus in case of any issues on Windows, at this time, you 
have to find workarounds yourself.

---
# Licensing

> [!NOTE]
> TL;DR: Research & development ✅| Production deployment ❌ (without commercial license)

The Noether Framework is licensed under a Non-Production License (based on Mistral AI's MNPL). This means you're free 
to use, modify, and research with the framework, but commercial/production use requires a separate commercial license 
from Emmi AI.

We're committed to open AI innovation while sustainably growing our business. For commercial licensing, contact 
us at partner@emmi.ai .

Read the full license [here](./LICENSE.txt).

---
# Endorsed by research groups from

<table>
  <tr>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Emmi-AI/noether/main/docs/source/_static/logos_cards/jku.png" height="50" alt="JKU Linz">
    </td>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Emmi-AI/noether/main/docs/source/_static/logos_cards/eth.png" height="50" alt="ETH Zurich">
    </td>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Emmi-AI/noether/main/docs/source/_static/logos_cards/upenn.png" height="50" alt="UPenn">
    </td>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Emmi-AI/noether/main/docs/source/_static/logos_cards/uw.png" height="50" alt="University of Washington">
    </td>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Emmi-AI/noether/main/docs/source/_static/logos_cards/tum.png" height="50" alt="TUM Munich">
    </td>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Emmi-AI/noether/main/docs/source/_static/logos_cards/sorbonne.png" height="50" alt="Sorbonne University">
    </td>
  </tr>
</table>

---
# Citing

If you use **Noether** in your research or industrial applications, please cite this repository. 
A formal BibTeX entry for our forthcoming ArXiv publication will be provided here shortly.

```bibtex
@misc{noether2026,
  author = { Bleeker, Maurits AND Hennerbichler, Markus AND Kuksa, Pavel },
  title = {Noether: A PyTorch-based Framework for Engineering AI},
  year = {2026},
  publisher = {GitHub},
  note = {Equal contribution},
  url = {https://github.com/Emmi-AI/noether}
}
```
