README.md

---
title: GeminiSim
emoji: ⚛️
colorFrom: gray
colorTo: yellow
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
short_description: 'Gradio app combining ASE simulations with Gemini AI. '
tags: [agent-demo-track, ASE, Gemini, Gradio]
---


# GeminiSim - An ASE-Gemini Agentic Demo

This project is a Gradio-based Agentic Demo for running atomic and molecular simulations using the [Atomic Simulation Environment (ASE)](https://wiki.fysik.dtu.dk/ase/), with natural language setup and analysis powered by Google's Gemini. Users can describe their simulation tasks in plain English, and the tool will set up, run, and analyze simulations automatically. [Video Presentation](https://mylifeunisaac-my.sharepoint.com/:v:/g/personal/63230615_mylife_unisa_ac_za/ETIgsxm_7x5Erxuub3LqmBYBn511VRGulyimNRm8BGTRow?nav=eyJyZWZlcnJhbEluZm8iOnsicmVmZXJyYWxBcHAiOiJPbmVEcml2ZUZvckJ1c2luZXNzIiwicmVmZXJyYWxBcHBQbGF0Zm9ybSI6IldlYiIsInJlZmVycmFsTW9kZSI6InZpZXciLCJyZWZlcnJhbFZpZXciOiJNeUZpbGVzTGlua0NvcHkifX0&e=Nn40pW)

---

## Features

- **Natural Language Interface:** Describe your simulation in everyday language.
- **Automated Setup:** Gemini interprets your request and generates ASE-compatible Python code.
- **Simulation Execution:** Runs the simulation (e.g., geometry optimization) using ASE.
- **Result Analysis:** Gemini summarizes and explains the simulation results.
- **Visual Output:** Gradio displays molecular structures and analysis.
- **Code Transparency:** View the generated Python code for reproducibility.

---

## Requirements

- Python 3.8+
- [ASE](https://wiki.fysik.dtu.dk/ase/)
- [Gradio](https://gradio.app/)
- [matplotlib](https://matplotlib.org/)
- [google-generativeai](https://pypi.org/project/google-generativeai/) (for Gemini API access)
- A Gemini API key

Install dependencies with:

```sh
pip install -r requirements.txt
```

---

## Usage

1. **Set your Gemini API Key**

   The application requires access to Gemini. Set your API key (replace with your actual key):

   ```python
   # In app.py
   genai.configure(api_key="YOUR_GEMINI_API_KEY")
   ```

   Or, set the key as an environment variable and update the script accordingly:

   ```sh
   export GEMINI_API_KEY="your-key-here"
   ```

2. **Run the Application**

   ```sh
   python app.py
   ```

3. **Open the Gradio Interface**

   After launching, Gradio will provide a local (and optionally public) web URL.  
   Enter your simulation instructions, such as:

   - "Optimize a water molecule and show the final geometry."
   - "Simulate a methane molecule and provide a summary of the bond lengths."

---

## How It Works

1. **Input:**  
   User provides a natural language description of the simulation task.

2. **LLM Parsing:**  
   Gemini interprets the description and generates ASE setup code.

3. **Simulation:**  
   The code is executed using ASE, running the required simulation.

4. **Analysis:**  
   Gemini analyzes the results and provides a summary.

5. **Output:**  
   The Gradio interface displays the molecular structure, analysis, and generated code.

---

## Security Note

- The current implementation uses `exec()` to run code generated by the LLM. **This is unsafe for untrusted input.**
- For production or public deployment, you must sandbox code execution (e.g., Docker, restricted Python environment).

---

## Customization

- Easily extend for other calculators, property analysis, or support for file uploads.
- Integrate additional ASE features or other simulation backends as needed.

---

## License

This project is provided under the MIT License. See [LICENSE](LICENSE) for details.

---

## Acknowledgments

- [Atomic Simulation Environment (ASE)](https://wiki.fysik.dtu.dk/ase/)
- [Gradio](https://gradio.app/)
- [Gemini](https://ai.google.dev/)