HackStack

Project Info

ChemSpec

Devpost

Inspiration

Chemistry education often relies on students memorizing complex chemical equations without ever witnessing the reactions themselves. Due to limited lesson time, curriculum constraints, and shrinking school budgets, teachers are unable to demonstrate many important experiments in the classroom. We wanted to bridge this gap by making chemical reactions more accessible, interactive, and memorable, giving every student the opportunity to see chemistry come to life regardless of their school's resources.

What it does

ChemSpec is a chemical reaction simulator aimed at teachers and students from sixth grade up to early undergraduate level. ChemSpec allows students to gain an understanding of various chemical reactions at both the molecular and observational level with the molecular simulation and 3D view, respectively. Upon inputting validated reactants, the student can watch a step-by-step molecular simulation of all the changes made to the reactants, with accompanying explanations. After this, the student can then see that same reaction play out like in the classroom - no need for safety goggles! ChemSpec simulates the predicted observations in a realistic 3D viewer and plays them out for the student to observe. The program takes care to also show observations that are normally invisible to the human eye so students can understand every aspect of the reaction. We also employ Codex to go one step deeper in reaction verification and analysis. Where ChemSpec's algorithm is unable to verify the validity of a reaction, users have the option to pass it off to Codex, which confirms or denies the reaction with an accompanying explanation and simulation. Alongside this, once users have finished viewing the 3D simulation, through Codex, they have the option to learn more about various aspects of the reaction. When requested, Codex will describe the conditions required for the reaction to take place, where it occurs in nature and/or in industry, as well as its common uses.

How we built it

We started with one important constraint: ChemSpec's core features should work without a stable internet connection. ChemSpec is a native Rust application built with Iced and wgpu, making it portable, light-weight, and accessible without an internet connection. We divided the app into three layers for parsing: chemical reasoning, rendering and AI integration. We built ChemSpec from the ground up using GPT 5.6 Sol. We began the project with a team-meeting discussing our intended outcome; once agreed, we handed off to a fresh thread, describing what we wanted to achieve and the components it would require. We requested Sol first ask us everything required to close out any assumptions, after which it was ready to write the implementation plan and specifications. Sol then worked through the stages it had specified. First, ChemSpec checks its brief reviewed reaction catalogue, then runs an algorithmic solver if the reaction is not present in this catalogue. The solver covers common reaction families and activity and solubility rules. If both paths decline, Codex can return a tightly constrained claim containing suggested products, conditions and observations. ChemSpec resolves and balances that claim locally before applying the same validation used for catalogue reactions. Atoms and molecules are represented as typed graphs. Each atom is stored as a node which contains its formal charge, number of unpaired/unbonded electrons, and its membership within a molecule. Reactions are represented as atomic graph transformations. The validation kernel checks that every atom is accounted for, charge and electrons are conserved, each bond or electron operation is legal, and the final molecular graphs match the products. Validated reactions are converted into renderer-independent frames containing the structural change. These frames create both a guided 2D molecular animation and a macroscopic 3D simulation. Playback is calculated from an absolute timeline and stable seed. Asynchronous work has generation IDs which allows ChemSpec to reject late Codex or validation results.

Challenges we ran into

Our key issue was identifying the proper implementation and architecture for the app's supported reaction families. When we initially allowed Codex to determine this for us, we fell into a time-eating trap of hard-coded, heavily researched, and non-dynamic reaction types. Once we had identified this as a key bottleneck for the project, we simplified the requirements for new reactions, solving large families algorithmically and then deferring all families we do not support to Codex.

Accomplishments we're proud of

Resolving thousands of reactions without requiring an internet connection or LLM, through an extensive and extendable resolver. Getting our native app working and on the web in its full form, still supporting thousands of reactions, and making it more accessible in the process. Creating a 3D simulation system that enables reactions to be accurately represented according to the state and colour of the reactants.

What we learned

When we initially allowed Codex to design the reaction architecture without proper review of its output, we ended up in a time-trap of only permitting hard-coded, non-dynamic reaction types. We learned to be explicit about our intended architecture upfront, and ensure we were aligned with the model. Using Codex to make quick UI mockups, such as in HTML and CSS, working incrementally until we were happy with the design, was much faster than incrementing through Iced's compile-and-run cycle, and gave the model a clear approved reference to compare against.

What's next

Organic structures have support for most reactions studied at high school/A-Level, however we aim to expand the scope of ChemSpec's organic branch to cover polymerisation as well as aromatic and carbonyl chemistry.

Analysis

Compare with all teams

View

Metric

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only
  • HTMLIn code
  • PythonIn code
  • RustIn code

3 of 3 appear in the indexed code.

AI coding agents

  • CodexConfig

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

5.0 MB

Source files

187

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.

0 stars