🧪 Chemistry Element Study Tool ⚛️

A fast, interactive Command-Line Interface (CLI) tool to explore, search, compare, and study chemical elements from the periodic table using a structured JSON database. Perfect for students, teachers, and devs who want a lightweight educational utility.

---

✨ Key Features

• 🔍 Study an element by Name, Symbol, or Atomic Number
• 🧭 Browse elements by Group or Period
• ⚖️ Compare two elements side-by-side
• 🔎 Keyword search across element data
• 🎲 Random element picker and a Daily Pick feature
• ✅ Lightweight JSON database (data/elements.json) for easy extension

---

Project Structure

chemistry_element_data/
├── data/
│   └── elements.json           # Core JSON database containing element properties
├── study/
│   ├── study_element.py        # Individual element lookup logic
│   ├── study_group.py          # Element lookup by Group
│   ├── study_period.py         # Element lookup by Period
│   └── study_compare.py        # Dual element comparison logic
├── tools/
│   ├── search.py               # Keyword search tool
│   ├── random_element.py       # Random element picker
│   ├── daily_element.py        # Daily featured element system
│   └── daily_elements.json     # Cached daily element state
├── main.py                     # Main Interactive CLI Menu (Entry Point)
├── LICENSE                     # Project License (MIT)
└── README.md                   # Documentation

---

Requirements

• Python 3.10 or newer
• Works cross-platform but tested on Debian-based Linux

---

Installation

Clone the repository and run:

git clone https://github.com/siyametj/chemistry_element_data.git
cd chemistry_element_data
python3 -m venv .venv        # optional but recommended
source .venv/bin/activate   # macOS / Linux
pip install -r requirements.txt  

---

Usage

Run the interactive CLI:

python3 main.py

Typical menu:

---

CHEMISTRY ELEMENT STUDY - MAIN MENU

1. Study Element (by name / symbol / number)
2. Study by Group
3. Study by Period
4. Compare Two Elements
5. Search Elements
6. Random Element
7. Exit

---

Example quick lookups (from scripts/tools):

• Study element by symbol (if CLI supports args): python3 main.py --element O
• Pick a random element: python3 tools/random_element.py
• Search keyword: python3 tools/search.py "alkaline"

(If you want CLI arguments support, I can add a small argparse wrapper.)

---

Data format

Elements are stored in data/elements.json as an array of element objects. Each element typically contains fields such as:

{
  "name": "Oxygen",
  "symbol": "O",
  "atomic_number": 8,
  "atomic_mass": 15.999,
  "group": 16,
  "period": 2,
  "category": "nonmetal",
  "electronegativity": 3.44,
  "standard_state": "gas",
  "density": 0.001429,
  "melting_point": 54.36,
  "boiling_point": 90.20,
  "discovery_year": 1774,
  "summary": "Essential for respiration and combustion"
}

Add or extend fields freely—tools use keys by name so keep them consistent.

---

Extending the Database

• Edit or add entries in data/elements.json.
• Keep keys consistent (name, symbol, atomic_number, group, period, etc.).
• If you add large data, consider adding import scripts to tools/.

---

Contributing

Contributions are welcome!

• Fork the repo
• Create a feature branch (feature/your-feature)
• Make your changes and add tests if applicable
• Open a Pull Request describing the change

Please follow these guidelines:

• Keep functions small and documented
• Update README when you add features
• Respect the existing JSON schema or document schema changes

---

Roadmap / Ideas

• Add CLI flags for non-interactive usage (e.g., --element, --compare a b)
• Add unit tests for study and search utilities
• Add fuzzy search and autocomplete
• Provide CSV import/export for elements
• Build a web UI (Flask / FastAPI) for visual browsing

---

License

This project is licensed under the MIT License — see the LICENSE file.

---

Author

Siyam (@siyametj)
GitHub: https://github.com/siyametj

---

If you found this tool helpful, please star the repo! ⭐