Maintaining an optimal acid base is important for the patient. The theory underlying acid–base balance can be challenging for clinicians and educators. These considerations justify creating simulations that include realistic changes to the partial pressure of carbon dioxide, pH, and bicarbonate ion concentration in a range of conditions. Our explanatory simulation application requires a model that derives these variables from total carbon dioxide content and runs in real time. The presented model is derived from the Stewart model, which is based on physical and chemical principles, and takes into account the effects of weak acids and strong ions on the acid–base balance. An inventive code procedure allows for efficient computation. The simulation results match target data for a broad range of clinically and educationally relevant disturbances of the acid–base balance. The model code meets the real-time goals of the application and can be applied in other educational simulations. Python model source code is made available.Supplementary InformationThe online version contains supplementary material available at 10.1186/s41077-023-00255-2.