Chemistry Helper

I built this project as a small web app in plain HTML, CSS, and JavaScript that can balance chemical reactions and show Lewis structures with simple shapes. The user types either a single chemical formula (such as H₂O, CO₂, NaCl) or a full reaction (such as CH₄ + O₂ → CO₂ + H₂O) into a text box. When they click the button, the app first decides whether the input is a reaction or just one formula, and then either balances the reaction or directly analyzes the molecule.

To understand the formulas, I wrote a simple parser that reads element symbols and their subscripts using a regular expression. For example, H₂O becomes an internal object like { H: 2, O: 1 }. For reactions, I remove spaces, split at the arrow (-> or =), and then split each side by “+” to get all reactants and products. Each of those pieces goes through the same formula parser, so I end up with a list of species, each with its element counts. This structure is then used both for reaction balancing and for later Lewis structure work.

For balancing reactions, I used a matrix (linear algebra) approach. I collect all distinct elements that appear and build a matrix where each row represents an element and each column represents a species. Reactant counts go in as positive and product counts as negative. I treat the last coefficient as fixed and solve the resulting linear system with Gaussian elimination using exact fractions (numerator and denominator) so there are no rounding errors. After I get a fractional solution, I scale everything by the least common multiple of denominators and then divide by the greatest common divisor, which produces the smallest whole-number coefficients.

To draw Lewis structures, I created a small periodic table in JavaScript that stores the number of valence electrons for common main-group elements. For a given formula, I first compute the total number of valence electrons. Then I choose a central atom by ignoring hydrogen and preferring the non-hydrogen element that appears once (for example, O in H₂O, N in NH₃, C in CH₄). If the formula appears to have multiple central atoms or is too complex (such as C₂H₆ or larger organic molecules), I mark it as “not supported” instead of guessing. For supported molecules, I put the central atom in the center, connect all other atoms to it with single bonds, and subtract those bonding electrons from the total.

Next, I distribute remaining electrons. I give outer atoms (except hydrogen) enough lone pairs to reach an octet as long as there are electrons left. Any electrons still left over go on the central atom as lone pairs. After that, I check whether the central atom has its target number of electrons. Most atoms want 8, but I treat B, Be, and Al as happy with 6, and I allow expanded octets for elements like P and S. If the central atom has too few electrons, the code converts lone pairs on outer atoms into multiple bonds (double or triple) until the central atom reaches its target. This produces an internal representation where each atom knows its bonds and lone pairs.

From this structure, I calculate the number of electron domains around the central atom: the number of bonds plus the number of lone pairs. Using simple VSEPR rules, I map these numbers to shape names such as linear, bent, trigonal planar, trigonal pyramidal, tetrahedral, trigonal bipyramidal, and octahedral. I then build an ASCII skeleton of the molecule, for example a cross shape for CH₄ or a simple line for CO₂. To show electrons, I take the valence electrons for each atom, subtract the electrons used in bonds, and then represent the remaining electrons with dots and colons next to the symbol following a fixed rule: 1 = “.”, 2 = “:”, 3 = “.:”, 4 = “::”, 5 = “::.”, and 6 = “:::”. This way, the user can see both bonding and non-bonding electrons in text form.

I also added special handling for cases that do not fit the general algorithm cleanly. Homonuclear diatomic molecules such as O₂, N₂, and Cl₂ are handled with a dedicated branch that assigns typical bond orders (single, double, or triple) and always marks them as linear. Ozone (O₃) is treated as a special case and forced to be bent, with a text note explaining that it is based on resonance between a single bond and a double bond to the central oxygen. In addition, I detect simple ionic compounds made from one metal and one nonmetal (for example NaCl, CaCl₂, MgO, Na₂O). For those, I assign typical ionic charges, check that the formula is neutral, and then display ions like Na⁺ and Cl::::⁻ with dots showing the electrons on each ion. These are labeled as ionic compounds with no single molecular shape, since ionic solids are lattices, not individual VSEPR molecules.

Finally, I added input validation and clear messages for limitations. If the input is empty or nonsense, the app shows an error instead of failing. If an element is missing from my valence table (for example, a transition metal like Fe in FeCl₃), the app explains that the element is not supported. If the formula uses parentheses or complex polyatomic ions in a way my parser does not handle (such as Ca(OH)₂ or Al₂(SO₄)₃), the result is marked as outside the main scope. Overall, the app combines a matrix method for balancing, a valence-electron–based Lewis algorithm, simple VSEPR rules, and a few chemistry special cases to give text-based Lewis structures, shapes, and balanced reactions in a simple browser interface.