ArshPathan commited on
Commit
a4752a5
·
1 Parent(s): d48a9c0

Upload folder using huggingface_hub

Browse files
Files changed (2) hide show
  1. README.md +97 -73
  2. 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
- <h3>AI-Driven Atomic Crystal Structure Engineering</h3>
20
- <p><i>Building the future of materials discovery through advanced reinforcement learning.</i></p>
21
 
22
- [![OpenEnv](https://img.shields.io/badge/Framework-OpenEnv-blueviolet?style=for-the-badge)](https://github.com/meta-pytorch/openenv)
23
  [![License: BSD](https://img.shields.io/badge/License-BSD-green?style=for-the-badge)](LICENSE)
24
- [![Hackathon: Meta OpenEnv](https://img.shields.io/badge/Hackathon-Meta%20OpenEnv-red?style=for-the-badge)](https://openenv.ai)
25
 
26
  </div>
27
 
28
  ---
29
 
30
- ## 🏗️ Project Overview
31
 
32
- **MaterialForge** is a high-fidelity Reinforcement Learning environment designed for the discovery and optimization of atomic crystal structures. Unlike simple grid-worlds, MaterialForge implements complex scientific heuristics that simulate the physical properties of real-world materials.
33
 
34
- ### 🚀 Key Innovations
 
 
 
 
35
 
36
- - **Advanced Physics Simulation:** Professional-grade heuristics using **Percolation Thresholds** for conductivity and **Gibbs-Stability** for structural integrity.
37
- - **Structural regularities:** Measures **Positional Entropy** and **Point-group Symmetry** to evaluate lattice order.
38
- - **Scientific Telemetry:** A custom laboratory dashboard providing deep analytics into crystalline growth.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
39
 
40
  ---
41
 
42
- ## 🧪 Scientific Architecture
 
 
43
 
44
- MaterialForge goes beyond simple placement. It simulates the **Structure-Function relationship** using three core scientific pillars:
45
 
46
- ### 1. The Physics Pipeline
47
 
48
  ```mermaid
49
- graph LR
50
- Lattice[Lattice Grid] --> BFS[BFS Search]
51
- BFS --> Percolation{Percolation?}
52
- Percolation -- Yes --> Cond[High Conductivity]
53
- Percolation -- No --> Ins[Insulating State]
 
 
 
 
 
54
 
55
- Lattice --> Symmetry[Mirror Plane Analysis]
56
- Symmetry --> Stability[Gibbs Stability Index]
57
 
58
- Lattice --> Entropy[Positional Entropy]
59
- Entropy --> Order[Lattice Order Index]
60
- ```
 
61
 
62
- ### 2. Atomic Species Data
63
 
64
- | Symbol | Element Type | Role | Hardness | Conductivity | Thermal | Cost |
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
- ## 📊 Environment Workflow
74
 
75
- The environment follows a standard Reinforcement Learning loop, optimized for large-scale evaluation via OpenEnv.
76
 
77
- ```mermaid
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
- ## 🏆 Scoring & Rubric
93
 
94
- The grading logic is designed to reward both **Scientific Accuracy** and **Material Efficiency**.
95
 
96
- ### Reward Formula
 
 
97
 
98
- $$R = (\alpha \cdot S_{stability} + \beta \cdot L_{order} + \gamma \cdot P_{accuracy}) - \text{Cost}_{quadratic}$$
99
 
100
- | Metric | Scientific Basis | Weighting |
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
- ## 🛠️ Getting Started
 
110
 
111
- ### Prerequisites
112
 
113
- - Python 3.10+
114
- - [uv](https://docs.astral.sh/uv/) (Recommended)
115
 
116
  ### Quick Launch
117
 
118
  ```bash
119
- # Clone
120
- git clone https://github.com/Arsh-Pathan/MaterialForge && cd MaterialForge
121
 
122
- # Initialize & Run
123
  uv run server
124
  ```
125
 
126
- ### Inference Test
127
 
128
- ```bash
129
- export API_BASE_URL="http://your-proxy"
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>Developed with ❤️ for the <b>Meta PyTorch OpenEnv Hackathon</b></p>
140
- <a href="https://huggingface.co/spaces/ArshPathan/material_forge_env"><b>View Live Lab Demo</b></a>
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
+ [![Framework: OpenEnv](https://img.shields.io/badge/Framework-OpenEnv-blueviolet?style=for-the-badge)](https://github.com/meta-pytorch/openenv)
22
  [![License: BSD](https://img.shields.io/badge/License-BSD-green?style=for-the-badge)](LICENSE)
23
+ [![Status: Production](https://img.shields.io/badge/Status-Production-orange?style=for-the-badge)](#)
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 create_app
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 the OpenEnv standard FastAPI app
34
- app = create_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