chemistry_paradise 1.1.26

data/doc/README.gen

@@ -0,0 +1,391 @@
+ADD_RUBY_BADGES
+ADD_LAST_UPDATE
+
+## 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.
+
+## 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 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 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 project - 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)
+
+## Potential useful links related to chemistry
+
+This is another good ruby-library for handling
+chemistry-related aspects:
+
+https://github.com/fogonthedowns/rubychem/
+
+ADD_CONTACT_INFORMATION

data/doc/todo/TODO.md

@@ -0,0 +1,26 @@
+- 1.32 * (10 ** -3) # => 0.00132
+x = 0.00132 # => 0.00132
+log x # => -2.87942606879415
+-(log x)
+# => 2.87942606879415
+
+^^^ chemparadise sollte diese steps angeben.
+
+
+- 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.
+
+- add sinatra parts at the least for calculating
+  the weight of the compoudd directly.  
+
+(4) 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.
+
+(5) Integrate:
+
+https://github.com/fogonthedowns/rubychem/
+   

data/lib/chemistry_paradise/base/base.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'chemistry_paradise/base/base.rb'; < ::ChemistryParadise::Base 
+# =========================================================================== #
+require 'chemistry_paradise/toplevel_methods/language.rb'
+require 'chemistry_paradise/shared.rb'
+require 'chemistry_paradise/constants/german_names_of_elements_to_element_symbol.rb'
+require 'chemistry_paradise/base/colours.rb'
+
+module ChemistryParadise
+
+class Base # === ChemistryParadise::Base
+
+  include ChemistryParadise::Constants
+  include ChemistryParadise::Shared
+
+  alias ee print
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === FILE_MOLECULAR_FORMULA_OF_DIFFERENT_MOLECULES
+  # ========================================================================= #
+  FILE_MOLECULAR_FORMULA_OF_DIFFERENT_MOLECULES =
+    "#{PROJECT_BASE_DIRECTORY}yaml/molecular_formula_of_different_molecules.yml"
+
+  # ========================================================================= #
+  # === reset
+  # ========================================================================= #
+  def reset
+  end
+
+  # ========================================================================= #
+  # === opnn
+  # ========================================================================= #
+  def opnn(i)
+    if i.is_a? String
+      i = { namespace: i }
+    end
+    Opn.opn(i) # Delegate to module Opn here.
+  end
+
+  # ========================================================================= #
+  # === use_which_language?
+  # ========================================================================= #
+  def use_which_language?
+    ::ChemistryParadise.use_which_language?
+  end
+
+  # ========================================================================= #
+  # === do_we_use_english?
+  #
+  # Query method to determine whether we will use english or whether
+  # we will use another language, for a project-wide setting.
+  # ========================================================================= #
+  def do_we_use_english?
+    (use_which_language? == :english)
+  end
+
+  # ========================================================================= #
+  # === set_commandline_arguments
+  # ========================================================================= #
+  def set_commandline_arguments(i = '')
+    i = [i].flatten.compact
+    @commandline_arguments = i
+  end
+
+  # ========================================================================= #
+  # === commandline_arguments?
+  # ========================================================================= #
+  def commandline_arguments?
+    @commandline_arguments
+  end
+
+  # ========================================================================= #
+  # === first_argument?
+  # ========================================================================= #
+  def first_argument?
+    @commandline_arguments.first
+  end; alias first? first_argument? # === first?
+
+  # ========================================================================= #
+  # === do_use_the_german_language
+  # ========================================================================= #
+  def do_use_the_german_language
+    ::ChemistryParadise.do_use_german
+  end
+
+  # ========================================================================= #
+  # === do_use_the_english_language
+  # ========================================================================= #
+  def do_use_the_english_language
+    ::ChemistryParadise.do_use_english
+  end
+
+end; end

data/lib/chemistry_paradise/base/colours.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'chemistry_paradise/base/colours.rb' 
+# =========================================================================== #
+module ChemistryParadise
+
+class Base # === ChemistryParadise::Base
+
+  begin
+    require 'colours'
+    include Colours
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === rev
+  # ========================================================================= #
+  def rev
+    ::Colours.rev
+  end
+
+  # ========================================================================= #
+  # === grey
+  # ========================================================================= #
+  def grey(i)
+    "#{Colours::GREY}#{i}#{Colours}#{rev}"
+  end
+
+  # ========================================================================= #
+  # === royalblue
+  # ========================================================================= #
+  def royalblue(i)
+    ::Colours.royalblue(i)
+  end
+
+  # ========================================================================= #
+  # === steelblue
+  # ========================================================================= #
+  def steelblue(i)
+    ::Colours.steelblue(i)
+  end
+
+  # ========================================================================= #
+  # === yellow
+  # ========================================================================= #
+  def yellow(i)
+    ::Colours.yellow(i)
+  end
+
+  # ========================================================================= #
+  # === teal
+  # ========================================================================= #
+  def teal(i)
+    Colours.teal(i)
+  end
+
+  # ========================================================================= #
+  # === sfancy
+  # ========================================================================= #
+  def sfancy(i)
+    ::Colours.sfancy(i)
+  end
+
+end; end

data/lib/chemistry_paradise/commandline/help.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'chemistry_paradise/commandline/help.rb'
+# =========================================================================== #
+module ChemistryParadise
+
+class ParseCommandline < ::ChemistryParadise::Base 
+
+  # ========================================================================= #
+  # === show_help
+  #
+  # The help options can be queried via:
+  #
+  #   chemistry_paradise --help
+  #
+  # ========================================================================= #
+  def show_help
+    e 'The following options are documented:'
+    e
+    e '  --molmassen?                     # show '\
+      'where the molmasses are kept (a file)'
+    e '  --electronegativity-of=F/Fe      # report '\
+      'the electronegativitiy of the elements F '\
+      'and Fe (Fluor and Iron)'
+    e '  --show_electron_negativity_chart # show '\
+      'the electron negativity chart of the atoms'
+    e '  --gtk-calculate-molecular-weight # to start '\
+      'the ruby-gtk3 wrapper for calculating the '\
+      'weight of compounds'
+    e '  /Quecksilber/                    # use '\
+      'a pseudo-regex to obtain the element-symbol '\
+      'from a german name'
+    e '  ^^^ the above // is called a pseudo-regex; pseudo '\
+      'because it is actually a String and not a regex'
+    e
+  end
+
+end; end