foamnordic 1.0.1__tar.gz

foamnordic-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hanseul Kang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

foamnordic-1.0.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: foamnordic
+Version: 1.0.1
+Summary: Integrated OpenFOAM coupling and computational modelling framework
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PentagonToy/FoamNordic
+Project-URL: Source, https://github.com/PentagonToy/FoamNordic
+Project-URL: Issues, https://github.com/PentagonToy/FoamNordic/issues
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: coloredlogs>=10.0
+Requires-Dist: filelock>=3.4.2
+Requires-Dist: foamlib<2,>=1.7
+Requires-Dist: GitPython<=3.1.43
+Requires-Dist: jinja2>=3.1.2
+Requires-Dist: numpy<3.0.0
+Requires-Dist: onsaemiro>=1.0.3
+Requires-Dist: packaging>=24.0
+Requires-Dist: protobuf<6,>=3.20.3
+Requires-Dist: psutil>=5.7.2
+Requires-Dist: pydantic>2
+Requires-Dist: pygithub>=2.3.0
+Requires-Dist: PyYAML>=6
+Requires-Dist: pyzmq>=25.1.2
+Requires-Dist: redis>=4.5
+Requires-Dist: tabulate>=0.8.9
+Requires-Dist: tqdm>=4.50.2
+Dynamic: license-file
+
+# FoamNordic
+
+FoamNordic provides Python-driven coupling and external model execution for
+OpenFOAM using SmartSim and SmartRedis.
+
+## Installation
+
+FoamNordic requires Python 3.10–3.12.
+
+```bash
+pip install foamnordic
+```
+
+## Build
+
+Activate your OpenFOAM environment first.
+
+For example:
+
+```bash
+module load openfoam
+```
+
+Or:
+
+```bash
+source /path/to/OpenFOAM/etc/bashrc
+```
+
+Then build the FoamNordic runtime and OpenFOAM integration:
+
+```bash
+foamnordic build
+```
+
+FoamNordic automatically prepares its SmartSim, SmartRedis, Redis, RedisAI,
+native SmartRedis, and OpenFOAM integration dependencies.
+
+To rebuild the runtime from a clean state:
+
+```bash
+foamnordic build --clobber
+```
+
+## Help
+
+Display the general help:
+
+```bash
+foamnordic --help
+```
+
+Display the build options:
+
+```bash
+foamnordic build --help
+```
+
+## Python
+
+```python
+import foamnordic as fno
+```
+
+## Documentation and Development
+
+Source code, development instructions, examples, and detailed documentation
+are available on GitHub:
+
+<https://github.com/PentagonToy/FoamNordic>
+
+## License
+
+FoamNordic is distributed under the MIT License.

foamnordic-1.0.1/README.md

@@ -0,0 +1,526 @@
+<p align="center">
+  <img src="icon.png" alt="FoamNordic" width="220">
+</p>
+
+<h1 align="center">FoamNordic</h1>
+
+<p align="center">
+  Python-driven OpenFOAM coupling and external model execution with SmartSim and SmartRedis.
+</p>
+
+---
+
+## Overview
+
+FoamNordic provides a Python interface for coupling OpenFOAM simulations with:
+
+- Python-based external models
+- SmartSim experiment management
+- SmartRedis data exchange
+- Custom OpenFOAM closures
+- External machine-learning operators
+- Local and HPC execution environments
+
+FoamNordic is designed to keep the Python API consistent across supported
+platforms while allowing the underlying OpenFOAM and MPI environments to be
+configured independently.
+
+---
+
+## Platform Support
+
+FoamNordic has been tested on the following platforms.
+
+### Linux
+
+- Native OpenFOAM installations
+- Module-based OpenFOAM installations
+- Local MPI execution
+- HPC environments using Slurm
+
+### macOS
+
+- Apple Silicon Macs
+- macOS systems supported by the native
+  [OpenFOAM.app](https://github.com/gerlero/openfoam-app)
+- Local MPI execution with Homebrew Open MPI
+
+The native macOS OpenFOAM application provides OpenFOAM in a case-sensitive,
+read-only virtual volume. This avoids compatibility issues caused by the
+case-insensitive default macOS filesystem.
+
+The current OpenFOAM.app release requires:
+
+- An Apple Silicon Mac
+- macOS 14 Sonoma or later
+
+For more information about installing and using native OpenFOAM on macOS,
+see the [OpenFOAM.app repository](https://github.com/gerlero/openfoam-app).
+
+---
+
+## Installation
+
+FoamNordic requires Python **3.10–3.12**.
+
+### PyPI
+
+Install the latest published version from PyPI:
+
+```bash
+pip install foamnordic
+```
+
+### GitHub
+
+Install the latest development version directly from GitHub:
+
+```bash
+pip install git+https://github.com/PentagonToy/FoamNordic.git
+```
+
+### Development Installation
+
+Clone the repository and install FoamNordic in editable mode:
+
+```bash
+git clone https://github.com/PentagonToy/FoamNordic.git
+cd FoamNordic
+pip install -e .
+```
+
+---
+
+## OpenFOAM Setup
+
+Before building FoamNordic, activate the OpenFOAM environment that it should
+use.
+
+### Linux
+
+With environment modules:
+
+```bash
+module load openfoam
+```
+
+Alternatively, source the OpenFOAM environment directly:
+
+```bash
+source /path/to/OpenFOAM/etc/bashrc
+```
+
+### macOS with OpenFOAM.app
+
+When installed with Homebrew, start an OpenFOAM session using:
+
+```bash
+openfoam
+```
+
+If OpenFOAM.app was installed manually, use the application-provided command:
+
+```bash
+/Applications/OpenFOAM-v2606.app/Contents/Resources/etc/openfoam
+```
+
+Replace the application name and path as necessary.
+
+The OpenFOAM environment must be active before running FoamNordic commands that
+build or execute OpenFOAM-based components.
+
+---
+
+## Building the Runtime
+
+Build the FoamNordic runtime and OpenFOAM integration:
+
+```bash
+foamnordic build
+```
+
+FoamNordic prepares the runtime components required for coupling OpenFOAM with
+SmartSim and SmartRedis, including:
+
+- Native SmartRedis libraries
+- OpenFOAM integration libraries
+- Runtime components for external model execution
+- OpenFOAM coupling support
+
+To rebuild the runtime from a clean state:
+
+```bash
+foamnordic build --clobber
+```
+
+Display available build options:
+
+```bash
+foamnordic build --help
+```
+
+Display general FoamNordic command-line help:
+
+```bash
+foamnordic --help
+```
+
+---
+
+## Python API
+
+Import FoamNordic as:
+
+```python
+import foamnordic as fno
+```
+
+A typical FoamNordic workflow is:
+
+```text
+Environment
+    ↓
+FoamCase
+    ↓
+Field / Closure Configuration
+    ↓
+Bridge
+    ↓
+SmartSim Experiment
+    ↓
+OpenFOAM ↔ SmartRedis ↔ Python
+```
+
+---
+
+## Environment
+
+Load an OpenFOAM environment from Python:
+
+```python
+environment = fno.Environment(
+    command="source /path/to/OpenFOAM/etc/bashrc",
+)
+
+environment.load()
+```
+
+Environment modules can be used in the same way:
+
+```python
+environment = fno.Environment(
+    command="module load openfoam",
+)
+
+environment.load()
+```
+
+On macOS with OpenFOAM.app, the environment command can point to the
+application-provided launcher:
+
+```python
+environment = fno.Environment(
+    command="/Applications/OpenFOAM-v2606.app/Contents/Resources/etc/openfoam",
+)
+
+environment.load()
+```
+
+---
+
+## FoamCase
+
+Create and initialise an OpenFOAM case:
+
+```python
+case = fno.FoamCase(
+    case_dir=CASE_DIR,
+    simulation_type="laminar",
+)
+
+report = case.initialize(
+    clean=True,
+    block_mesh=True,
+    validate_mesh=True,
+    n_subdomains=4,
+)
+```
+
+The initialisation workflow can:
+
+- Clean the case directory
+- Run `blockMesh`
+- Validate the mesh
+- Prepare the requested number of subdomains
+
+---
+
+## Field Coupling
+
+### OpenFOAM to Python
+
+Configure fields transferred from OpenFOAM to Python:
+
+```python
+field_inputs = case.configure(
+    operator=None,
+    fields=["U", "p"],
+    direction="of -> db",
+    transfer_at="each",
+)
+```
+
+### Python to OpenFOAM
+
+Configure fields transferred from Python back to OpenFOAM:
+
+```python
+field_outputs = case.configure(
+    operator=None,
+    fields=["U"],
+    direction="db -> of",
+    transfer_at="each",
+)
+```
+
+### Derived OpenFOAM Fields
+
+Derived OpenFOAM fields can be requested directly:
+
+```python
+field_inputs = case.configure(
+    operator=None,
+    fields=[
+        "U",
+        "p",
+        "T",
+        "H2O",
+        "grad(T)",
+    ],
+    direction="of -> db",
+    transfer_at="each",
+)
+```
+
+---
+
+## Bridge
+
+Create the field exchange interface:
+
+```python
+bridge = fno.Bridge(
+    handshake_mode="blocking",
+    retention_steps=10,
+)
+```
+
+Connect the configured inputs and outputs:
+
+```python
+field_exchanger = bridge.couple(
+    inputs=field_inputs,
+    outputs=field_outputs,
+)
+```
+
+Fields are available directly from each coupling step:
+
+```python
+for step in field_exchanger.steps(
+    client=client,
+    database=db,
+    experiment=exp,
+    model=model,
+):
+    velocity = step["U"]
+    pressure = step["p"]
+
+    step.send(U=velocity)
+```
+
+---
+
+## External Operators
+
+External models can be connected to OpenFOAM through `fno.Operator`.
+
+For example, create an ONNX operator:
+
+```python
+operator = fno.Operator.onnx(
+    model_path=MODEL_PATH,
+    inputs=["grad(U)", "delta"],
+    outputs=["nut"],
+)
+```
+
+An OpenFOAM closure can then be configured:
+
+```python
+closure = case.configure_closure(
+    model="smartSimNut",
+)
+```
+
+Connect the external operator and closure through the bridge:
+
+```python
+closure_exchanger = bridge.couple(
+    inputs=closure_inputs,
+    outputs=closure_outputs,
+    operator=operator,
+    closure=closure,
+)
+```
+
+Evaluate the external operator at each exchange step:
+
+```python
+for step in closure_exchanger.steps(
+    client=client,
+    database=db,
+    experiment=exp,
+    model=model,
+):
+    outputs = closure_exchanger.evaluate(step)
+    step.send(**outputs)
+```
+
+---
+
+## Mathematical Operations
+
+`fno.Math` provides OpenFOAM field expressions and algebraic operations.
+
+Examples include:
+
+```python
+fno.Math.grad(...)
+fno.Math.div(...)
+fno.Math.curl(...)
+fno.Math.laplacian(...)
+fno.Math.mag(...)
+fno.Math.symm(...)
+fno.Math.dev(...)
+```
+
+Mesh-dependent differential operations can be evaluated by OpenFOAM, while
+algebraic operations can be used in external Python models.
+
+---
+
+## SmartSim and SmartRedis
+
+FoamNordic exposes SmartSim and SmartRedis directly when lower-level runtime
+control is required:
+
+```python
+experiment = fno.smartsim.Experiment(...)
+client = fno.smartredis.Client(...)
+```
+
+This keeps OpenFOAM-specific coupling inside FoamNordic while preserving direct
+access to:
+
+- SmartSim experiment management
+- SmartRedis clients
+- Database communication
+- External model execution
+
+---
+
+## MPI and HPC Execution
+
+FoamNordic supports independent configuration of the OpenFOAM and MPI
+environments.
+
+### Local MPI
+
+Local MPI execution can be configured using the MPI implementation available on
+the host system.
+
+On macOS, Homebrew Open MPI can be used for local execution:
+
+```bash
+brew install open-mpi
+```
+
+### Slurm
+
+Linux HPC environments using Slurm are supported. OpenFOAM cases and external
+models can be launched through the configured SmartSim experiment and cluster
+environment.
+
+The exact launcher and resource configuration depend on the target system and
+cluster configuration.
+
+---
+
+## macOS Notes
+
+When using OpenFOAM.app:
+
+1. Start an OpenFOAM session by opening the application or running:
+
+   ```bash
+   openfoam
+   ```
+
+2. Build FoamNordic from within the active OpenFOAM environment:
+
+   ```bash
+   foamnordic build
+   ```
+
+3. Store user-compiled OpenFOAM solvers and libraries in the user directories:
+
+   ```bash
+   $FOAM_USER_APPBIN
+   $FOAM_USER_LIBBIN
+   ```
+
+4. Be aware that macOS uses Apple's Clang compiler rather than the GCC compiler
+   commonly used on Linux.
+
+5. Cases or libraries that depend on case-sensitive filenames may require a
+   separate case-sensitive disk image.
+
+The OpenFOAM installation itself is not user-writable by design. Additional
+solvers and libraries should be installed in the user-specific OpenFOAM
+directories.
+
+---
+
+## Examples
+
+The repository includes example workflows for:
+
+- Laminar field coupling with `lidDrivenCavity`
+- Reacting-flow field coupling with `counterFlowFlame`
+- External Smagorinsky LES closure
+- External `k`-equation LES closure
+
+---
+
+## Development
+
+Clone the repository and install FoamNordic in editable mode:
+
+```bash
+git clone https://github.com/PentagonToy/FoamNordic.git
+cd FoamNordic
+pip install -e .
+```
+
+After installation, FoamNordic can be imported directly from the working tree:
+
+```python
+import foamnordic as fno
+```
+
+---
+
+## License
+
+FoamNordic is distributed under the **MIT License**.

foamnordic-1.0.1/README_PYPI.md

@@ -0,0 +1,74 @@
+# FoamNordic
+
+FoamNordic provides Python-driven coupling and external model execution for
+OpenFOAM using SmartSim and SmartRedis.
+
+## Installation
+
+FoamNordic requires Python 3.10–3.12.
+
+```bash
+pip install foamnordic
+```
+
+## Build
+
+Activate your OpenFOAM environment first.
+
+For example:
+
+```bash
+module load openfoam
+```
+
+Or:
+
+```bash
+source /path/to/OpenFOAM/etc/bashrc
+```
+
+Then build the FoamNordic runtime and OpenFOAM integration:
+
+```bash
+foamnordic build
+```
+
+FoamNordic automatically prepares its SmartSim, SmartRedis, Redis, RedisAI,
+native SmartRedis, and OpenFOAM integration dependencies.
+
+To rebuild the runtime from a clean state:
+
+```bash
+foamnordic build --clobber
+```
+
+## Help
+
+Display the general help:
+
+```bash
+foamnordic --help
+```
+
+Display the build options:
+
+```bash
+foamnordic build --help
+```
+
+## Python
+
+```python
+import foamnordic as fno
+```
+
+## Documentation and Development
+
+Source code, development instructions, examples, and detailed documentation
+are available on GitHub:
+
+<https://github.com/PentagonToy/FoamNordic>
+
+## License
+
+FoamNordic is distributed under the MIT License.