Spaces:
Running
Running
Commit ·
a4752a5
1
Parent(s): d48a9c0
Upload folder using huggingface_hub
Browse files- README.md +97 -73
- server/app.py +3 -4
README.md
CHANGED
|
@@ -16,126 +16,150 @@ base_path: /web
|
|
| 16 |
<div align="center">
|
| 17 |
<img src="server/static/hero.png" width="100%" alt="MaterialForge Hero">
|
| 18 |
<h1>🔬 MaterialForge</h1>
|
| 19 |
-
<
|
| 20 |
-
<p><i>Building the future of materials discovery through advanced reinforcement learning.</i></p>
|
| 21 |
|
| 22 |
-
[](https://github.com/meta-pytorch/openenv)
|
| 23 |
[](LICENSE)
|
| 24 |
-
[![
|
| 25 |
|
| 26 |
</div>
|
| 27 |
|
| 28 |
---
|
| 29 |
|
| 30 |
-
##
|
| 31 |
|
| 32 |
-
**MaterialForge** is a high-fidelity
|
| 33 |
|
| 34 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 35 |
|
| 36 |
-
|
| 37 |
-
|
| 38 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 39 |
|
| 40 |
---
|
| 41 |
|
| 42 |
-
## 🧪 Scientific
|
|
|
|
|
|
|
| 43 |
|
| 44 |
-
|
| 45 |
|
| 46 |
-
|
| 47 |
|
| 48 |
```mermaid
|
| 49 |
-
|
| 50 |
-
|
| 51 |
-
|
| 52 |
-
|
| 53 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 54 |
|
| 55 |
-
|
| 56 |
-
Symmetry --> Stability[Gibbs Stability Index]
|
| 57 |
|
| 58 |
-
|
| 59 |
-
|
| 60 |
-
|
|
|
|
| 61 |
|
| 62 |
-
###
|
| 63 |
|
| 64 |
-
|
| 65 |
-
| :----- | :------------ | :-------------- | :------- | :----------- | :------ | :--- |
|
| 66 |
-
| **A** | **Metal** | Structural Core | 0.9 | 0.4 | 0.2 | 8 |
|
| 67 |
-
| **B** | **Conductor** | Signal Sync | 0.2 | 0.9 | 0.1 | 6 |
|
| 68 |
-
| **C** | **Ceramic** | Thermal Plate | 0.6 | 0.1 | 0.9 | 4 |
|
| 69 |
-
| **P** | **Polymer** | Elastic Linker | 0.1 | 0.2 | 0.3 | 2 |
|
| 70 |
|
| 71 |
---
|
| 72 |
|
| 73 |
-
## 📊
|
| 74 |
|
| 75 |
-
|
| 76 |
|
| 77 |
-
|
| 78 |
-
sequenceDiagram
|
| 79 |
-
participant Agent as LLM Agent
|
| 80 |
-
participant MF as MaterialForge Env
|
| 81 |
-
participant PE as Physics Engine
|
| 82 |
-
|
| 83 |
-
Agent->>MF: Action (Place Atom)
|
| 84 |
-
MF->>PE: Calculate Structural Properties
|
| 85 |
-
PE-->>MF: Percolation + Symmetry + Entropy
|
| 86 |
-
MF->>MF: Calculate Reward (Quadratic Cost)
|
| 87 |
-
MF-->>Agent: Observation + Reward
|
| 88 |
-
```
|
| 89 |
|
| 90 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 91 |
|
| 92 |
-
##
|
| 93 |
|
| 94 |
-
The
|
| 95 |
|
| 96 |
-
|
|
|
|
|
|
|
| 97 |
|
| 98 |
-
|
| 99 |
|
| 100 |
-
|
| 101 |
-
| :------------------ | :------------------------------------- | :-------- |
|
| 102 |
-
| **Stability Index** | Mirror symmetry & coordination bonding | 30% |
|
| 103 |
-
| **Order Index** | Homogeneity & sub-lattice entropy | 20% |
|
| 104 |
-
| **Property Delta** | L2-norm distance to target vector | 40% |
|
| 105 |
-
| **Efficiency** | Quadratic penalty for budget overruns | 10% |
|
| 106 |
|
| 107 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 108 |
|
| 109 |
-
|
|
|
|
| 110 |
|
| 111 |
-
|
| 112 |
|
| 113 |
-
|
| 114 |
-
- [uv](https://docs.astral.sh/uv/) (Recommended)
|
| 115 |
|
| 116 |
### Quick Launch
|
| 117 |
|
| 118 |
```bash
|
| 119 |
-
#
|
| 120 |
-
|
| 121 |
|
| 122 |
-
#
|
| 123 |
uv run server
|
| 124 |
```
|
| 125 |
|
| 126 |
-
###
|
| 127 |
|
| 128 |
-
|
| 129 |
-
|
| 130 |
-
export API_KEY="your-key"
|
| 131 |
-
export MODEL_NAME="your-model"
|
| 132 |
-
|
| 133 |
-
uv run python inference.py
|
| 134 |
-
```
|
| 135 |
|
| 136 |
---
|
| 137 |
|
| 138 |
<div align="center">
|
| 139 |
-
<p>
|
| 140 |
-
<a href="https://huggingface.co/spaces/ArshPathan/material_forge_env"><b>
|
| 141 |
</div>
|
|
|
|
| 16 |
<div align="center">
|
| 17 |
<img src="server/static/hero.png" width="100%" alt="MaterialForge Hero">
|
| 18 |
<h1>🔬 MaterialForge</h1>
|
| 19 |
+
<p><b>An Advanced Reinforcement Learning Sandbox for Atomic Crystal Engineering</b></p>
|
|
|
|
| 20 |
|
| 21 |
+
[](https://github.com/meta-pytorch/openenv)
|
| 22 |
[](LICENSE)
|
| 23 |
+
[](#)
|
| 24 |
|
| 25 |
</div>
|
| 26 |
|
| 27 |
---
|
| 28 |
|
| 29 |
+
## 🏛️ Executive Summary
|
| 30 |
|
| 31 |
+
**MaterialForge** is a high-fidelity environment designed for the discovery of optimal crystal structures. It simulates the structure-property relationship of materials using advanced physics heuristics, challenging AI agents to evolve a lattice grid from an amorphous state into highly ordered crystalline structures that meet target thermal and electrical specifications.
|
| 32 |
|
| 33 |
+
---
|
| 34 |
+
|
| 35 |
+
## 🏗️ System Architecture
|
| 36 |
+
|
| 37 |
+
MaterialForge follows a decoupled architectural pattern, ensuring that pure-physics logic is separated from the interactive server and the RL-loop orchestration.
|
| 38 |
|
| 39 |
+
```mermaid
|
| 40 |
+
graph TD
|
| 41 |
+
subgraph "Agent Workspace"
|
| 42 |
+
Agent[LLM Agent]
|
| 43 |
+
end
|
| 44 |
+
|
| 45 |
+
subgraph "MaterialForge Environment"
|
| 46 |
+
API[FastAPI / WebSocket Interface]
|
| 47 |
+
Engine[Lattice Management Engine]
|
| 48 |
+
Physics[Advanced Physics Heuristics]
|
| 49 |
+
Rubric[Multi-Objective Reward System]
|
| 50 |
+
end
|
| 51 |
+
|
| 52 |
+
subgraph "Observations & State"
|
| 53 |
+
State[(8x8 Atomic Grid)]
|
| 54 |
+
Props[Property Vector]
|
| 55 |
+
Phase[Phase Classification]
|
| 56 |
+
end
|
| 57 |
+
|
| 58 |
+
Agent -->|MaterialForgeAction| API
|
| 59 |
+
API --> Engine
|
| 60 |
+
Engine -->|Compute| Physics
|
| 61 |
+
Physics -->|Properties| Rubric
|
| 62 |
+
Rubric -->|Reward + Observation| API
|
| 63 |
+
API -->|Feedback| Agent
|
| 64 |
+
Engine --> State
|
| 65 |
+
Physics --> Props
|
| 66 |
+
Physics --> Phase
|
| 67 |
+
```
|
| 68 |
|
| 69 |
---
|
| 70 |
|
| 71 |
+
## 🧪 Scientific Foundations
|
| 72 |
+
|
| 73 |
+
The environment implements three primary physical models to simulate material behavior at a heuristic level.
|
| 74 |
|
| 75 |
+
### 1. Percolation & Conductivity
|
| 76 |
|
| 77 |
+
Conductivity is determined by the **Percolation Threshold**. The engine identifies connected pathways of Conductive Atoms (Species B) across the lattice.
|
| 78 |
|
| 79 |
```mermaid
|
| 80 |
+
flowchart LR
|
| 81 |
+
Start([Action Applied]) --> Search[BFS Pathway Search]
|
| 82 |
+
Search --> Connectivity{Continuous Path?}
|
| 83 |
+
Connectivity -- "Span X-Axis" --> MultB[+4.0 Multiplier]
|
| 84 |
+
Connectivity -- "Span Y-Axis" --> MultC[+2.5 Multiplier]
|
| 85 |
+
Connectivity -- "No Path" --> Low[Base Value Only]
|
| 86 |
+
MultB --> Result[Conductivity Property Result]
|
| 87 |
+
MultC --> Result
|
| 88 |
+
Low --> Result
|
| 89 |
+
```
|
| 90 |
|
| 91 |
+
### 2. Structural Stability (Gibbs Approach)
|
|
|
|
| 92 |
|
| 93 |
+
Stability is derived from local coordination numbers and mirror-plane symmetry.
|
| 94 |
+
|
| 95 |
+
- **Coordination bonding**: Rewards atoms with a higher local neighbor density.
|
| 96 |
+
- **Mirror Symmetry**: Symmetry across central axes stabilizes the lattice against thermal stress.
|
| 97 |
|
| 98 |
+
### 3. Lattice Order (Entropy)
|
| 99 |
|
| 100 |
+
Measures the **Positional Entropy** of atoms. Highly ordered crystalline structures (Symmetric and Homogeneous) yield the highest "Lattice Order Index".
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 101 |
|
| 102 |
---
|
| 103 |
|
| 104 |
+
## 📊 Interaction Model
|
| 105 |
|
| 106 |
+
### Action Space
|
| 107 |
|
| 108 |
+
Agents interact via discrete operations on the 8x8 lattice:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 109 |
|
| 110 |
+
| Action | Description | Scientific Intent |
|
| 111 |
+
| :-------- | :---------------------------------------------- | :---------------------------------- |
|
| 112 |
+
| `place` | Inserts an atom into an empty cell. | Material Growth |
|
| 113 |
+
| `replace` | Swaps an existing atom for a different species. | Lattice Refinement |
|
| 114 |
+
| `remove` | Clears a cell. | Defect Management / Budget Recovery |
|
| 115 |
|
| 116 |
+
### Observation Space
|
| 117 |
|
| 118 |
+
The environment returns a rich state-vector containing:
|
| 119 |
|
| 120 |
+
- **Grid Snapshot**: Full 2D array representation.
|
| 121 |
+
- **Property Vector**: Current [Hardness, Conductivity, Thermal, Elasticity].
|
| 122 |
+
- **Score Breakdown**: Granular feedback on Stability and Order.
|
| 123 |
|
| 124 |
+
---
|
| 125 |
|
| 126 |
+
## 🏆 Scoring Rubric
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 127 |
|
| 128 |
+
The reward signal $R$ is calculated to incentivize scientific accuracy while enforcing material efficiency.
|
| 129 |
+
|
| 130 |
+
```mermaid
|
| 131 |
+
pie title Reward Distribution
|
| 132 |
+
"Property Alignment" : 40
|
| 133 |
+
"Structural Stability" : 30
|
| 134 |
+
"Lattice Order" : 20
|
| 135 |
+
"Phase Bonus" : 10
|
| 136 |
+
```
|
| 137 |
|
| 138 |
+
> [!IMPORTANT]
|
| 139 |
+
> **Quadratic Cost Pressure**: Every action incurs an atomic cost. If the total cost exceeds the budget, a **quadratic penalty** is applied: $Penalty = (Cost_{total} - Budget)^2$. This forces agents to build efficiently rather than filling the grid blindly.
|
| 140 |
|
| 141 |
+
---
|
| 142 |
|
| 143 |
+
## 🛠️ Developer Integration
|
|
|
|
| 144 |
|
| 145 |
### Quick Launch
|
| 146 |
|
| 147 |
```bash
|
| 148 |
+
# Install dependencies
|
| 149 |
+
uv sync
|
| 150 |
|
| 151 |
+
# Start the environment server
|
| 152 |
uv run server
|
| 153 |
```
|
| 154 |
|
| 155 |
+
### Interactive Playground
|
| 156 |
|
| 157 |
+
Access the high-fidelity laboratory dashboard at:
|
| 158 |
+
`http://localhost:8000/playground`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 159 |
|
| 160 |
---
|
| 161 |
|
| 162 |
<div align="center">
|
| 163 |
+
<p>Built with ❤️ by <b>Arsh Pathan</b> for the Meta PyTorch OpenEnv Hackathon</p>
|
| 164 |
+
<a href="https://huggingface.co/spaces/ArshPathan/material_forge_env"><b>Launch Production Discovery Lab</b></a>
|
| 165 |
</div>
|
server/app.py
CHANGED
|
@@ -15,7 +15,7 @@ from pathlib import Path
|
|
| 15 |
|
| 16 |
# OpenEnv runtime integration
|
| 17 |
try:
|
| 18 |
-
from openenv.core.env_server.http_server import
|
| 19 |
except ImportError as e:
|
| 20 |
raise ImportError("OpenEnv-Core is required. Please install via 'uv sync'.") from e
|
| 21 |
|
|
@@ -30,12 +30,11 @@ def _env_factory():
|
|
| 30 |
return MaterialForgeEnvironment(rubric=HeuristicRewardRubric())
|
| 31 |
|
| 32 |
|
| 33 |
-
# Initialize
|
| 34 |
-
app =
|
| 35 |
_env_factory,
|
| 36 |
MaterialForgeAction,
|
| 37 |
MaterialForgeObservation,
|
| 38 |
-
env_name="material_forge_env",
|
| 39 |
max_concurrent_envs=4,
|
| 40 |
)
|
| 41 |
|
|
|
|
| 15 |
|
| 16 |
# OpenEnv runtime integration
|
| 17 |
try:
|
| 18 |
+
from openenv.core.env_server.http_server import create_fastapi_app
|
| 19 |
except ImportError as e:
|
| 20 |
raise ImportError("OpenEnv-Core is required. Please install via 'uv sync'.") from e
|
| 21 |
|
|
|
|
| 30 |
return MaterialForgeEnvironment(rubric=HeuristicRewardRubric())
|
| 31 |
|
| 32 |
|
| 33 |
+
# Initialize a clean OpenEnv FastAPI app (disabling default Gradio interface)
|
| 34 |
+
app = create_fastapi_app(
|
| 35 |
_env_factory,
|
| 36 |
MaterialForgeAction,
|
| 37 |
MaterialForgeObservation,
|
|
|
|
| 38 |
max_concurrent_envs=4,
|
| 39 |
)
|
| 40 |
|