GY-63_MS5611/libraries/AtomicWeight/README.md

145 lines
4.7 KiB
Markdown
Raw Normal View History

2022-12-30 11:29:07 -05:00
[![Arduino CI](https://github.com/RobTillaart/AtomicWeight/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
[![Arduino-lint](https://github.com/RobTillaart/AtomicWeight/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/AtomicWeight/actions/workflows/arduino-lint.yml)
[![JSON check](https://github.com/RobTillaart/AtomicWeight/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/AtomicWeight/actions/workflows/jsoncheck.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/AtomicWeight/blob/master/LICENSE)
[![GitHub release](https://img.shields.io/github/release/RobTillaart/AtomicWeight.svg?maxAge=3600)](https://github.com/RobTillaart/AtomicWeight/releases)
# AtomicWeight
Arduino library for atomic weights.
## Description
This library is mainly as a base for educational purposes.
2022-12-31 12:30:42 -05:00
Learning the **periodic table of elements**, the abbreviations and weight.
2022-12-31 11:38:51 -05:00
It also provides the number of electrons, neutrons and protons per element.
Furthermore the library has a **weight()** function, that returns the weight
of either an element or by formula. See examples.
Note: library is still experimental. More testing is needed.
2022-12-30 11:29:07 -05:00
#### internal
2022-12-31 11:38:51 -05:00
The PTOE class uses a table that has compressed weight to save RAM
- it stores weights as **uint16_t**, 0..65535 instead of floats.
- weight factor = 222.909 = (65535.0 / heaviest element = 118)
- error < 0.3%
- the table (and thus the class) does not handle isotopes.
2022-12-30 11:29:07 -05:00
## Interface
```cpp
#include "AtomicWeight.h"
```
2022-12-31 12:30:42 -05:00
The parameter **element** in the following functions is 0..118.
(element 0 being a single neutron).
2022-12-30 11:29:07 -05:00
- **PTOE()** Constructor (Periodic Table Of Elements)
- **uint8_t electrons(uint8_t element)** returns the number of electrons of the element.
- **uint8_t neutrons(uint8_t element)** returns the number of neutrons of the element.
- **uint8_t protons(uint8_t element)** returns the number of protons of the element.
2022-12-31 11:38:51 -05:00
- **float weight(uint8_t element)** returns the weight of the element.
2022-12-31 12:30:42 -05:00
The error < 0.3%, table uses "weight compression".
2023-01-02 07:02:36 -05:00
- **float weight(char \* formula, char \* abbreviation == NULL)** see below.
- If (el != NULL) returns the total weight of one element in a formula
- if (el == NULL) returns the weight of the whole formula
- Returns 0 if it cannot parse the formula given.
- **float massPercentage(char \* formula, char \* abbreviation)**
Returns mass percentage of a selected element in a formula
2022-12-30 11:29:07 -05:00
- **uint8_t find(char \* abbreviation)** returns the element number.
- **char \* name(uint8_t element)** returns the abbreviation of element.
2022-12-31 12:30:42 -05:00
#### weight
2022-12-31 11:38:51 -05:00
2023-01-02 07:02:36 -05:00
The **weight(int n)** call returns the weight of a single atom (by index).
The **weight(formula)** call is meant to calculate the weight of a molecule.
A molecule defined as one or more atoms.
2022-12-31 12:30:42 -05:00
The latter function does not care about the order of the atoms.
So "C6H6" is equal to "H6C6" or even "CCCCCCHHHHHH" or "C3H3C3H3" etc.
2023-01-02 07:02:36 -05:00
Elements are defined as one or two characters long.
The first must be upper case, the (optional) second must be lower case.
2022-12-31 11:38:51 -05:00
If no number is provided the count of 1 is assumed.
2022-12-31 12:30:42 -05:00
The functions returns a float, so to get the integer weight, one should use **round()**.
If the formula is not parseable it will return a weight of 0.
(Since 0.1.2)
The weight formula parsing experimentally supports brackets () to indicate groups in the formula.
Valid formula's might look as:
- "B" = single element
- "Na" = single element
- "C6" = single element, multiple times
- "H2SO4" compound molecule, no groups
- "C6(COOH)2" compound molecule, with repeating groups
- "YBa2Cu3O7" some superconductor-ish material
2022-12-31 11:38:51 -05:00
2023-01-02 07:02:36 -05:00
(Since 0.1.3)
The **weight(formula, element)** function is meant to calculate the total weight of one element
in a molecule. E.g one can weigh the H atoms in H2O (2 of 18).
2022-12-31 12:30:42 -05:00
#### debug
- **float weightFactor()** returns weightFactor.
2022-12-31 11:38:51 -05:00
2022-12-30 11:29:07 -05:00
## Operation
See examples
## Future
#### must
- improve documentation
#### should
2022-12-31 12:30:42 -05:00
- add examples
- extend formula parser with error codes.
2022-12-31 11:38:51 -05:00
#### could
2022-12-31 12:30:42 -05:00
- extend unit tests
2022-12-30 11:29:07 -05:00
- state table
- liquid, gas, solid, unknown (2 bits per element) = ~30 bytes
- (short) table of English names
- which ones ?
2022-12-31 11:38:51 -05:00
- function **float atomicPercentage("H2O", "H")** ~33%
2022-12-31 12:30:42 -05:00
- performance functions
- especially **find()** ?
2022-12-31 11:38:51 -05:00
- case (in)sensitive **find()**
2023-01-02 07:02:36 -05:00
- is there a faster data structure?
- search by nr is O(1)
- search by name is O(n)
2022-12-30 11:29:07 -05:00
#### wont (unless)
2022-12-31 11:38:51 -05:00
- parameters element should be less than \_size
- user responsibility
2022-12-30 11:29:07 -05:00
- more information?
- database needed
2022-12-31 11:38:51 -05:00
- Electron bands K L M etc?
2022-12-30 11:29:07 -05:00
- temperatures,
- melt
- evaporate
- 2 bytes per temp 4 x 118 = 476 bytes
- compression 3 bytes for 2 temps 2x 12 bits = 0..4095 K = 354 bytes