chemistry_paradise 1.4.2

data/chemistry_paradise.gemspec

@@ -0,0 +1,46 @@
+# =========================================================================== #
+# Gemspec for Project Chemistry.
+# =========================================================================== #
+require 'chemistry_paradise'
+require 'roebe/toplevel_methods/misc.rb'
+
+Gem::Specification.new { |s|
+
+  s.name    = 'chemistry_paradise'
+  s.version = ChemistryParadise::VERSION
+  s.date    = Time.now.strftime('%Y-%m-%d')
+
+  DESCRIPTION = <<-EOF
+
+  Chemistry-related tasks are gathered in this project.
+    
+  The classes in this project may allow you to translate
+  between celsius and fahrenheit (and vice versa), show the
+  mass of elements or compounds and several similar things
+  somewhat related to chemistry.
+
+  For more extensive documentation, see the link at the
+  bottom right side of this webpage, called "Documentation".
+
+  EOF
+
+  s.summary     = DESCRIPTION
+  s.description = DESCRIPTION
+
+  s.extra_rdoc_files = %w()
+  
+  s.authors  = ['Robert A. Heiler']
+  s.email    = Roebe.email?
+  s.files    = Dir['**/*']
+  s.license  = 'MIT'
+  s.homepage = 'https://rubygems.org/gems/chemistry_paradise'
+
+  s.required_ruby_version     = '>= '+Roebe.third_most_stable_version_of_ruby
+  s.required_rubygems_version = '>= '+Gem::VERSION
+  s.rubygems_version          = '>= '+Gem::VERSION
+
+  s.add_dependency 'opn'
+  s.add_dependency 'cliner'
+  s.add_dependency 'colours'
+
+}

data/doc/README.gen

@@ -0,0 +1,595 @@
+DEFAULT_HEADER
+
+## 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 <b>sciruby</b>.
+
+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
+<b>C16H12N2</b>, 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 <b>@language</b> 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 <b>Quecksilber</b>
+for the element <b>Hg</b> (mercury, aka <b>hydrargyrum</b>).
+
+The file <b>german_names_of_elements_to_element_symbol.rb</b>
+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
+
+<b>class ChemistryParadise::ShowElectronNegativityOfThisElement</b>
+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, <b>/</b> acts as the separator between several elements.
+
+<b>Always input the element symbol, NOT the long name of the
+element.</b>
+
+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 <b>1.5</b> between
+the two elements; ideally <b>1.8</b>. Past that point it can
+be concluded, that two different elements with such a large
+discrepancy in their electron negativity values, would form 
+<b>ionic bonds</b> (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:
+
+<img src="https://i.imgur.com/kY95n2d.png">
+
+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 <b>August 2022</b> the <b>temperature calculator</b> has been
+improved a bit in ruby-gtk3. It now looks like this:
+
+<img src="https://i.imgur.com/1CeRd5z.png" style="margin: 1em">
+
+Furthermore, if a number is inputted into the first entry then
+the other entries are <b>automatically</b> 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 <b>Mg</b>. 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
+<b>ChemistryParadise.sanitize()</b>. 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 <b>wetter</b> is german for <b>weather</b>.
+
+Code residing in the <b>module Wetter</b> 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:
+
+<img src="https://i.imgur.com/uZGAQrJ.png" style="margin: 1em">
+
+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 <b>November 2021</b> (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: <b>H</b> and <b>He</b>.
+
+The second row has <b>Li</b>, <b>Be</b> and so forth.
+
+In <b>April 2023</b> 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:
+
+<img src="https://github.com/monsieurmoneybags/periodic_table/raw/main/periodic_table.png" style="margin: 1em">
+
+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 <b>H</b> 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 <b>ChemistryParadise::ShowPeriodicTable</b> handles
+this step.
+
+It looks like this:
+
+<img src="https://i.imgur.com/3BF4AYj.png" style="margin: 1em">
+
+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 <b>ruby-library</b> for handling
+chemistry-related aspects:
+
+https://github.com/fogonthedowns/rubychem/
+
+CONTACT_INFORMATION

data/doc/bugs/BUGS.md

@@ -0,0 +1,16 @@
+This file will keep some known bugs.
+
+(1) molmasse 'Al(NO3)'
+
+
+
+/Programs/Ruby/1.9.3p448/lib/ruby/site_ruby/1.9.1/chemistry/shared.rb:69:in `convert_parens': undefined method `[]' for nil:NilClass (NoMethodError)
+        from /Programs/Ruby/1.9.3p448/lib/ruby/site_ruby/1.9.1/chemistry/split_molecule_names.rb:19:in `set_input'
+        from /Programs/Ruby/1.9.3p448/lib/ruby/site_ruby/1.9.1/chemistry/split_molecule_names.rb:15:in `initialize'
+        from /Users/x/DATA/PROGRAMMING_LANGUAGES/RUBY/SRC/chemistry/lib/chemistry/calculate_atomic_mass.rb:70:in `new'
+        from /Users/x/DATA/PROGRAMMING_LANGUAGES/RUBY/SRC/chemistry/lib/chemistry/calculate_atomic_mass.rb:70:in `run'
+        from /Users/x/DATA/PROGRAMMING_LANGUAGES/RUBY/SRC/chemistry/lib/chemistry/calculate_atomic_mass.rb:25:in `initialize'
+        from /Users/x/DATA/PROGRAMMING_LANGUAGES/RUBY/SRC/chemistry/lib/chemistry/calculate_atomic_mass.rb:110:in `new'
+        from /Users/x/DATA/PROGRAMMING_LANGUAGES/RUBY/SRC/chemistry/lib/chemistry/calculate_atomic_mass.rb:110:in `<main>'
+
+^^^ BUG! It should not fail.

data/doc/formulas/biochemical_calculations.md

@@ -0,0 +1,5 @@
+Dilution formula            | c1 · V1 = c2 · V2
+Concentration               | c = n/V
+Amount of substance         | n = c×V
+Molar mass                  | M = m/n
+Mass                        | m = M·n

data/doc/todo/todo_for_the_chemistry_paradise_project.md

@@ -0,0 +1,33 @@
+--------------------------------------------------------------------------------
+(1) → 1.32 * (10 ** -3) # => 0.00132
+      x = 0.00132 # => 0.00132
+      log x # => -2.87942606879415
+      -(log x)
+# => 2.87942606879415
+      ^^^ chemparadise sollte diese steps angeben.
+--------------------------------------------------------------------------------
+(2) → we should ahve an interactive periodensystem
+      that tells us which periods we have. not sure
+      if this shall be integrated into the shell
+      or be separate.
+--------------------------------------------------------------------------------
+(3) → add sinatra parts at the least for calculating
+      the weight of the compoudd directly.
+      In the ruby-gtk3, add a small number on the bottom
+      left area, to indicate the atomic number of that
+      element at hand. This should be subscript or so,
+      perhaps via pango? hmm.
+--------------------------------------------------------------------------------
+(4) → Integrate:
+
+      https://github.com/fogonthedowns/rubychem/
+--------------------------------------------------------------------------------
+(5) → we want to be able to compare two different formulas to
+      one another, including suggesting how to complement them.
+--------------------------------------------------------------------------------
+
+ chemical = RubyChem::Equation.new("C12H26+O2=CO2+H2O")
+ chemical.balance
+ "2C12H26 + 37O2 = 24C1O2 + 26H2O1" 
+ ^^^^ make this possible in chemistry-paradise
+