This gem was last updated on the 10.11.2023 (dd.mm.yyyy notation), at 16:25:50 o'clock.
Introduction
This project bundles together some commonly used methods and classes related to chemistry.
Use cases may include when you want to quickly know the molecular weight of a compound (via the commandline) or when you want to want to perform a simple combustion analysis, so mostly homework, school, college or simple university-related use cases.
Please keep in mind that this is just a hobby project. It will never compete with professional or commercial-grade projects, simply because that is not its main use case or goal. It's also not my primary project related to science - I am more of a molecular biology person, so the code in this project is mostly just "helper"-related code. Perhaps you may find some interesting ideas in the long run, though, and other chemistry-related projects in ruby could benefit from it. See also sciruby.
For more information, have a look at the other documentation in this file (respectively at https://www.rubydoc.info/gems/chemistry_paradise/ ).
The individual classes in this project
The individual classes of this project may have their own subsection here, starting with class CalculateAtomicMass, which was one of the first classes originally written - I had to calculate the mass of compounds via a pocket calculator. Since I kept doing mistakes doing so, I decided to write some code that will show whether I calculated correctly.
class ChemistryParadise::CalculateAtomicMass
class ChemistryParadise::CalculateAtomicMass will calculate the mass of compounds.
Argument to this class should be something such as C16H12N2, but you can also use Unicode numbers such as ₃ rather than 3.
So the following shows valid arguments to the class:
ChemistryParadise::CalculateAtomicMass.new('C16H12N2')
ChemistryParadise::CalculateAtomicMass.new('CH3Cl')
ChemistryParadise::CalculateAtomicMass.new('CH₃Cl') # ← This variant also works since as of December 2019.
ChemistryParadise::CalculateAtomicMass.new('CO₂') # ← As does this, too, since as of December 2019.
If you need english output, look at the entry default language to use within the project, in this file.
ChemistryParadise::Orbitals will simply show how many electrons fit into an orbital.
The class ChemistryParadise::ShowElectronConfiguration will report the electron configuration for the given element.
For example, if you pass 'Fe' as element (iron), then the class will report something like this:
Found element Fe. It has 26 electrons.
[Ar] 4s2 3d6
Specific example in pure ruby:
require 'chemistry_paradise'
ChemistryParadise::ShowElectronConfiguration.new('Fe')
Note that this may not work as well for heavy atoms, but for the more common ~smaller atoms, it should work fine.
Do note that since as of March 2020 a few chemical substances can be quickly queried by their trivial name, including a few german names.
Example:
molmasse harnstoff
This would be the very same as:
molmasse CH₄N₂O
molmasse CH4N2O
To output this in english, try:
molmasse "(NH₄)₂SO₄" --english
So basically use the --english commandline flag.
Default language to use within the project
The project initially showed output mostly in the german language.
However had - most people may prefer the english language, so a switch exists that allows you to toggle the behaviour of the ChemistryParadise project, in regards to the language at hand.
If you wish to use the english language, you can use the following method call:
ChemistryParadise.do_use_english
Also, the Base class allows one to switch between the english and the german language.
Either way, past this point, if you invoke class CalculateAtomicMass, it will then report the result in english. Internally the module-method instance variable called @language will keep track of the language at hand.
See also the test/ subdirectory to look at this in action.
German names of atoms/elements
In the german language, we can find names such as Quecksilber for the element Hg (mercury, aka hydrargyrum).
The file german_names_of_elements_to_element_symbol.rb handles this conversion, but you can also query the translated symbol-name from the commandliny, by using a pseudo-regex such as:
chemistry_paradise /Quecksilber/
So in other words, the german name of the element at hand is to be put between the two / characters.
The default pseudo-regex may change one day, in which case the change would be properly documented here as well.
class ChemistryParadise::ShowElectronNegativityOfThisElement
class ChemistryParadise::ShowElectronNegativityOfThisElement can be used to show, on the commandline, the electronegativity of the given elements.
So for example, if you'd want to know to know the electron negativity of Fluor and Iron, you'd pass in this:
ChemistryParadise::ShowElectronNegativityOfThisElement.new(['F','Fe'])
From the commandline, if you aliased towards the .rb file, simply pass in F and Fe, without any ' quotes.
If you want another accessor, also from the commandline, then do:
chemistry_paradise --electronegativity-of=F/Fe
In that case, / acts as the separator between several elements.
Always input the element symbol, NOT the long name of the element.
See wikipedia for a complete list of elements.
If you intent to use this part of the chemistry_paradise project to predict whether two elements form an ionic bond, as a rule of thumb, the difference should be at the very least 1.5 between the two elements; ideally 1.8. Past that point it can be concluded, that two different elements with such a large discrepancy in their electron negativity values, would form ionic bonds (if they would bind to one another in the first place, that is).
Showing the individual steps
If you wish to display the molecular mass of some compound, on the commandline, and would also like to display the individual steps done, you can use the following commandline flag:
mmasse CaCO3 --show-steps
Note that this will probably be extended in the future, so that this also works a bit like a debug-flag. The idea here is to be able to verify what is going on in a simple manner, rather than to merely rely on the output assumed to be correct.
class ChemistryParadise::CombustionAnalysis
class ChemistryParadise::CombustionAnalysis can be used to analyse the combustion of a compound.
Say that you know these values:
K 28,93%
S 23,72%
O 47.35%
K means Kalium aka Sodium (correction in November 2020: Sodium is, of course, Na aka Natrium; not sure why the german name matches, whereas the english one does not, but evidently I made the mistake in assuming that Kalium would be Sodium, which was evidently incorrect).
Note that 28,93% refers to 28.93% of 100% of the given substance is stored in Kalium.
Next, we invoke the class from the commandline; I aliased it to combustionanalysis.
combustionanalysis "K 28,93% S 23,72% O 47.35%"
The output will be:
KSO₄
combustionanalysis "Al 15,77% O 56,12% S 28,11%" # => Al₂O12S₃
Note that this may have a few bugs left, for larger compounds or any combustion analysis that is not very correct. But for simple compounds, such as the examples shown above, it should work very well.
You can use this from ruby code via:
require 'chemistry_paradise/combustion_analysis.rb'
ChemistryParadise::CombustionAnalysis.new(ARGV)
# To use the example above:
ChemistryParadise::CombustionAnalysis.new('Al 15,77% O 56,12% S 28,11%') # => Al₂O₁₂S₃
Disclaimer
Keep in mind that this is merely a hobby project, not a "fully fledged professional" suite of code.
I use it primarily to help me in little things, such as querying the electron configuration of an atom on the commandline, or calculating the molar mass of a compound. I could do the latter manually, but computers are a lot faster and a lot less work than manual calculations - and more reliable, too. I tend to do errors when typing anything into a calculator.
As this is not professional chemistry-software, please do not expect that this project could ever really help calculating the Schroedinger equation or anything similar to that.
Www-related documentation in german and english
Since as of January 2021 I have decided to slowly put my local knowledge base about chemistry online. These were mostly stored in .cgi files. I may put them into sinatra as interface eventually; we'll see. Anyway, this is a low priority, ongoing effort, and the german parts will not be too useful for other people - but still, I wanted to publish it, simply because it seems to be more useful when available in combination with ruby code as well..
Since as of May 2021 there is also a tiny sinatra API available.
For example, if you start sinatra.rb, and then visit a page such as:
http://localhost:4567/compound/H2SO4
The atomic mass of H2SO4 will be calculated and then shown via that web-interface.
GUI
I may in the long run add GUIs similar to this one here:
http://www.gamgi.org/images/screenshot13_5b.png
But this is a hobby project, so don't expect too much work going into it. See the image below for how that GUI part currently looks like, in regards to the chemistry_paradise project. This depends on the ruby-gtk3 bindings. Once you have the necessary C-files (glib, atk, pango, cairo, gtk), doing "gem install gtk3" should work just fine. On windows this is a bit more tedious though.
For now have a look at the gtk3/ subdirectory in this gem. But there isn't that much there. Just buttons with different colours really ... this needs more functionality, evidently! ;-)
Since as of February 2021, if you need to calculate the molecular weight of a compound and want to use a GUI, try:
require 'chemistry_paradise/gui/gtk3/calculate_molecular_weight/calculate_molecular_weight.rb'
ChemistryParadise::GUI::Gtk::CalculateMolecularWeight.run
This depends on the ruby-gtk3 bindings.
Or, from the commandline, try:
chemistry_paradise --gtk-calculate-molecular-weight
You can also view the periodic table via a ruby-gtk3 wrapper. This currently (May 2021) looks like this:
The two lower entries can be used to calculate the atomic weight. The example shows H2O aka water. Note that this has a few bugs here and there - it's not quite polished. I only wanted to showcase the prototype really.
In August 2022 the temperature calculator has been improved a bit in ruby-gtk3. It now looks like this:
Furthermore, if a number is inputted into the first entry then the other entries are automatically calculated. A libui variant was added as well, thus allowing you to use this on windows more easily, and I also added a java-swing variant, to make it even simpler on windows to work with it (even if ruby is not available there).
YAML files (.yml) distributed with this gem
This subsection will briefly mention the .yml files that are currently (May 2021) part of this project.
electron_negativity_chart.yml: This file keeps track of the "Pauling electronegativity scale". In theory this could be used for distance-calculation as well, but it really is just a simple (stupid) file that keeps track of the old Pauling scores.
atomgewichte.yml: This file keeps track of the molecular weight of the individual atoms. The name is still german; not sure if I will change it to english, but for now it'll remain in german, due to historic reasons mostly (this project was started with german output on the commandline, many years ago).
colours_for_the_elements.yml: Here you can specify which colours to use for the ruby-gtk3 widget. This is probably not very important for many people though.
molecular_formula_of_different_molecules.yml: This file may be used to keep track of some common substances, in regards to their formula. Note that not every molecule can be found there, logically; it just showcases a few examples and may then be re-used in different parts, such as the GUI elements.
Licence
Since as of June 2021 the licence for the chemistry_paradise project is now MIT. I encourage folks to contribute code or documentation, but ultimately the project is mostly a "I needed these things done, so I wrote the code, then I moved on to do other things".
You can see the MIT licence here:
https://opensource.org/licenses/MIT
The individual .rb files that are part of the chemistry_paradise project do not contain that licence header, simply because I can not want to be bothered to read through legalese that doesn't add anything to code or documentation - but if you ever need an "official" licence, it is here stated that the project is now under the MIT licence, and this is also specified in the .gemspec file that is used to create this gem - see the .gem file that you can download from rubygems.org.
Todo list
This is just a generic todo list.
Add sinatra-bindings so that the above can be used on the www as well.
Add fxruby and tk bindings as well.
Extend the ruby-gtk3 widgets while retaining support for ruby-gtk2.
Calculating the atomic mass of an element
Let's take the example of the element Mg. It has different isotopes:
²⁴Mg 78,99% 23,985
²⁵Mg 10,00% 24,985
²⁶Mg 11,01% 25,983
To calculate the atomic mass here use the following toplevel API:
ChemistryParadise.calculate_atomic_mass_based_on_isotope_percentage(78.99, 23.985, 10.00, 24.985, 11.01, 25.983)
It's a bit cumbersome API, but this is mostly owing to the fact that I wanted to add this quickly, to solve an existing problem.
Sanitizing a chemical formula
Say that you have citrulline, an aminoacid, with the following chemical formula:
C6H13N3O3
The more correct way to write this down is:
C₆H₁₃N₃O₃
So, simply use numbers via subscript.
There is a method that can help with this conversion, called ChemistryParadise.sanitize(). This may not be extremely useful, but is just a tiny helper method; may be interesting to integrate it in a webpage or a GUI.
Usage example:
ChemistryParadise.sanitize('C6H13N3O3') # => "C₆H₁₃N₃O₃"
The Wetter submodule
Introduction
The name wetter is german for weather.
Code residing in the module Wetter namespace will relate to the weather in general. For instance, calculating pressure of air at a specific altitude. No such code has been added for this yet, but it may happen in the future.
Until then, the Wetter submodule contains a bit of helper-code for querying wetter-related information. In February 2023 functionality and code was also added to allow this to happen when openssl is unavailable - in such an event ruby's open-uri would normally not work and instead print out a specific OpenSSL related error.
The Sinatra interface of the Wetter module
To start the sinatra interface, do:
wetter --sinatra
Graphical User Interface (GUI) of the Wetter module
To start the ruby-gtk3 wrapper, try:
wetter --gtk # ← This now defaults to ruby-gtk3
wetter --gtk3
Note that you have to have the two gems gtk3 and gtk_paradise installed in order for this to work. This is not terribly useful anyway; it was mostly done just for quick demo purposes, what is possible. Anyone wanting to improve on this is welcome to give it a try. :)
As of 30.08.2021 (August 2021) a widget in libui also exists now. This has the advantage that it works on windows out of the box, if you did install the libui gem on windows.
Commandline invocation goes via:
wetter --libui
Incomplete "unified widgets" bindings also exist; I may eventually add support for ruby-tk, fxruby as well as gosu - but we'll see.
The ruby-gtk3 wrapper looks like this on my system:
This is not extremely pretty, but I wanted to keep it simple; if others want modifications then drop me an email. Otherwise I'll just keep it as it is for now.
Fahrenheit to Celsius table as a reminder
32 °F 0 °C freezing/melting point of water
40 °F 4.44 °C
50 °F 10.00 °C
60 °F 15.56 °C
70 °F 21.11 °C room temperature
80 °F 26.67 °C
90 °F 32.22 °C
98.6 °F 37 °C average body temperature
100 °F 37.78 °C
110 °F 43.33 °C
120 °F 48.89 °C
130 °F 54.44 °C
140 °F 60.00 °C
150 °F 65.56 °C
160 °F 71.11 °C
170 °F 76.67 °C
180 °F 82.22 °C
190 °F 87.78 °C
200 °F 93.33 °C
Deprecations of the Wetter submodule
In November 2021 (02.11.2021) support for ruby-gtk2 was removed as far as the wetter gem is concerned. I am not completely abandoning ruby-gtk2 in general, but for the small wetter app it is simply easier to use ruby-gtk3 instead - and ruby-gtk3 looks better as well, via CSS rules.
Convenience methods for obtaining individual rows of the periodic table
The periodic table of elements has seven rows.
The first row has only two elements: H and He.
The second row has Li, Be and so forth.
In April 2023 I noticed a small shell script that will print out the periodic table on the commandline. The project can be found here:
https://github.com/monsieurmoneybags/periodic_table
The image it will yield on the commandline may look like this:
I found this feature neat, so I wanted to add it to the chemistry_paradise gem.
In order to do this, I decided to first add seven helper methods: one for each row.
So, the following toplevel methods were added:
ChemistryParadise.row1
ChemistryParadise.period1 # simply an alias to the ^^^ above
ChemistryParadise.row2
ChemistryParadise.period2 # simply an alias to the ^^^ above
ChemistryParadise.row3
ChemistryParadise.period3 # simply an alias to the ^^^ above
ChemistryParadise.row4
ChemistryParadise.period4 # simply an alias to the ^^^ above
ChemistryParadise.row5
ChemistryParadise.period5 # simply an alias to the ^^^ above
ChemistryParadise.row6
ChemistryParadise.period6 # simply an alias to the ^^^ above
ChemistryParadise.row7
ChemistryParadise.period7 # simply an alias to the ^^^ above
These methods will return all elements in that given row.
For instance:
ChemistryParadise.row1 # => ["H", "He"]
Will return an Array showing H and He (Hydrogen and Helium).
Whereas:
ChemistryParadise.row2 # => ["Li", "Be", "B", "C", "N", "O", "F", "Ne"]
Would return the elements Li, Be, B and so forth.
This was a necessary first step, before adding support for displaying the elements on the commandline.
See the next subsection for more information pertaining this feature.
Showing the periodic table on the commandline
As mentioned elsewhere in this document, it is possible, since as of April 2023, to quickly display the periodic table on the commandline.
This functionality was inspired by a shell script written by someone else. class ChemistryParadise::ShowPeriodicTable handles this step.
It looks like this:
Unfortunately it is also significantly longer in code than the shell script. On the plus side, though, feature-wise, it is trivial to change the colours, whereas the shell script uses some hardcoded values as-is.
Potential useful links related to chemistry
This is another good ruby-library for handling chemistry-related aspects:
https://github.com/fogonthedowns/rubychem/
Contact information and mandatory 2FA coming up in 2022
If your creative mind has ideas and specific suggestions to make this gem more useful in general, feel free to drop me an email at any time, via:
shevy@inbox.lt
Before that email I used an email account at Google gmail, but in 2021 I decided to slowly abandon gmail, for various reasons. In order to limit the explanation here, allow me to just briefly state that I do not feel as if I want to promote any Google service anymore when the user becomes the end product (such as via data collection by upstream services, including other proxy-services). My feeling is that this is a hugely flawed business model to begin with, and I no longer wish to support this in any way, even if only indirectly so, such as by using services of companies that try to promote this flawed model.
In regards to responding to emails: please keep in mind that responding may take some time, depending on the amount of work I may have at that moment. So it is not that emails are ignored; it is more that I have not (yet) found the time to read and reply. This means there may be a delay of days, weeks and in some instances also months. There is, unfortunately, not much I can do when I need to prioritise my time investment, but I try to consider all feedback as an opportunity to improve my projects nonetheless.
In 2022 rubygems.org decided to make 2FA mandatory for every gem owner eventually:
see https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
Mandatory 2FA will eventually be extended to all rubygems.org developers and maintainers. As I can not use 2FA, for reasons I will skip explaining here, this means that my projects will eventually be removed, as I no longer have any control over my projects hosted on rubygems.org (because I can not use 2FA).
At that point, I no longer have any control what is done to my projects since whoever is controlling the gems ecosystem took away our control here. I am not sure at which point ruby became corporate-controlled - that was not the case several years ago, so something has changed.
Ruby also only allows 2FA users to participate on the issue tracker these days:
https://bugs.ruby-lang.org/issues/18800
But this has been reverted some months ago, so it is no longer applicable. Suffice to say that I do not think that we should only be allowed to interact on the world wide web when some 'authority' authenticated us, such as via mandatory 2FA, so I hope this won't come back again.
Fighting spam is a noble goal, but when it also means you lock out real human people then this is definitely NOT a good situation to be had.