-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation overhaul part 1
- Loading branch information
Showing
35 changed files
with
1,625 additions
and
1,225 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| (chemistry)= | ||
|
|
||
| # Chemical Formulas | ||
|
|
||
| pyEQL interprets the chemical formula of a substance to calculate its molecular | ||
| weight and formal charge. The formula is also used as a key to search the | ||
| database for parameters (e.g. diffusion coefficient) that are used in subsequent | ||
| calculations. | ||
|
|
||
| ## How to Enter Valid Chemical Formulas | ||
|
|
||
| Generally speaking, type the chemical formula of your solute the "normal" way | ||
| and `pyEQL` should be able to inerpret it. Internally, `pyEQL` uses the [`pymatgen.core.ion.Ion`](https://pymatgen.org/pymatgen.core.html#pymatgen.core.ion.Ion) | ||
| class to "translate" chemical formulas into a consistent format. Anything that the `Ion` class can understand will | ||
| be processed into a valid formula by `pyEQL`. | ||
|
|
||
| Here are some examples: | ||
|
|
||
| | Substance | You enter | `pyEQL` understands | | ||
| | :--- | :---: | :---: | | ||
| | Sodium Chloride | "NaCl", "NaCl(aq)", or "ClNa" | "NaCl(aq)" | | ||
| | Sodium Sulfate | "Na(SO4)2" or "NaS2O8" | "Na(SO4)2(aq)" | | ||
| | Sodium Ion | "Na+", "Na+1", "Na1+", or "Na[+]" | "Na[+1]" | | ||
| | Magnesium Ion | "Mg+2", "Mg++", or "Mg[++]" | "Mg[+2]" | | ||
| | Methanol | "CH3OH", "CH4O" | "'CH3OH(aq)'" | | ||
|
|
||
| Specifically, `pyEQL` uses `Ion.from_formula(<formula>).reduced_formla` (shown in the right hand column of the table) to | ||
| identify solutes. Notice that for charged species, the charges are always placed inside square brackets (e.g., `Na[+1]`) | ||
| and always include the charge number (even for monovalent ions). Uncharged species are always suffixed by `(aq)` to | ||
| disambiguate them from solids. | ||
|
|
||
| :::{important} | ||
| **When writing multivalent ion formulas, it is strongly recommended that you put the charge number AFTER the + or - | ||
| sign** (e.g., type "Mg+2" NOT "Mg2+"). The latter formula is ambiguous - it could mean $`Mg_2^+`$ or $`Mg^{+2}`$ | ||
| ::: | ||
|
|
||
| (manual-testing)= | ||
| ## Manually testing a formula | ||
|
|
||
| If you want to make sure `pyEQL` is understanding your formula correctly, you can manually test it via `pymatgen` as | ||
| follows: | ||
|
|
||
| ``` | ||
| >>> from pymatgen.core.ion import Ion | ||
| >>> Ion.from_formula(<your_formula>).reduced_formula | ||
| ... | ||
| ``` | ||
|
|
||
| ## Formulas you will see when using `Solution` | ||
|
|
||
| When using the `Solution` class, | ||
|
|
||
| - When creating a `Solution`, you can enter chemical formulas in any format you prefer, as long as `pymatgen` can understand it (see [manual testing](#manually-testing-a-formula)). | ||
| - The keys (solute formulas) in `Solution.components` are preserved in the same format the user enters them. So if you entered `Na+` for sodium ion, it will stay that way. | ||
| - Arguments to `Solution.get_property` can be entered in any format you prefer. When `pyEQL` queries the database, it will automatically convert the formula to the canonical one from `pymatgen` | ||
| - Property data in the database is uniquely identified by the canonical ion formula (output of `Ion.from_formula(<formula>).reduced_formla`, e.g. "Na[+1]" for sodium ion). |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| (class-solution)= | ||
|
|
||
| # The Solution Class | ||
|
|
||
| The `Solution` class defines a pythonic interface for **creating**, **modifying**, and **estimating properties** of | ||
| electrolyte solutions. It is the core feature of `pyEQL` and the primary user-facing class. | ||
|
|
||
| ## Creating a solution | ||
|
|
||
| A `Solution` created with no arguments will default to pure water at pH=7, T=25 degrees Celsius, and 1 atm pressure. | ||
|
|
||
| ``` | ||
| >>> from pyEQL import Solution | ||
| >>> s1 = Solution() | ||
| >>> s1.pH | ||
| 6.998877352386266 | ||
| ``` | ||
|
|
||
| Alternatively, you can use the `autogenerate()` function to easily create common solutions like seawater: | ||
|
|
||
| ``` | ||
| >>> from pyEQL.functions import autogenerate | ||
| >>> s2 = autogenerate('seawater') | ||
| <pyEQL.solution.Solution object at 0x7f057de6b0a0> | ||
| ``` | ||
|
|
||
| You can inspect the solutes present in the solution via the `components` attribute. This comprises a dictionary of solute formula: moles, where 'moles' is the number of moles of that solute in the `Solution`. Note that the solvent (water) is present in `components`, too. | ||
|
|
||
| ``` | ||
| >>> s2.components | ||
| {'H2O': 55.34455401423017, | ||
| 'H+': 7.943282347242822e-09, | ||
| 'OH-': 8.207436858780226e-06, | ||
| 'Na+': 0.46758273714962967, | ||
| 'Mg+2': 0.052661180523467986, | ||
| 'Ca+2': 0.010251594148212318, | ||
| 'K+': 0.010177468379526856, | ||
| 'Sr+2': 9.046483353663286e-05, | ||
| 'Cl-': 0.54425785619973, | ||
| 'SO4-2': 0.028151873448454025, | ||
| 'HCO3-': 0.001712651176926199, | ||
| 'Br-': 0.0008395244921424563, | ||
| 'CO3-2': 0.00023825904349479546, | ||
| 'B(OH)4': 0.0001005389715937341, | ||
| 'F-': 6.822478260456777e-05, | ||
| 'B(OH)3': 0.0003134669156396757, | ||
| 'CO2': 9.515218476861175e-06 | ||
| } | ||
| ``` | ||
|
|
||
| To get the amount of a specific solute, use `get_amount()` and specify the units you want: | ||
|
|
||
| ``` | ||
| >>> s2.get_amount('Na+', 'g/L') | ||
| <Quantity(10.6636539, 'gram / liter')> | ||
| ``` | ||
|
|
||
| Finally, you can manually create a solution with any list of solutes, temperature, pressure, etc. that you need: | ||
|
|
||
| ``` | ||
| >>> from pyEQL import Solution | ||
| >>> s1 = Solution(solutes={'Na+':'0.5 mol/kg', 'Cl-': '0.5 mol/kg'}, | ||
| pH=8, | ||
| temperature = '20 degC', | ||
| volume='8 L' | ||
| ) | ||
| ``` | ||
|
|
||
| ## Class reference | ||
|
|
||
| The remainder of this page contains detailed information on each of the methods, attributes, and properties in `Solution`. Use the sidebar on the right for easier navigation. | ||
|
|
||
| ```{eval-rst} | ||
| .. autoclass:: pyEQL.Solution | ||
| :members: | ||
| :inherited-members: | ||
| :private-members: _get_property | ||
| :special-members: __init__ | ||
| :member-order: bysource | ||
| ``` |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.