Metadata-Version: 2.4
Name: molmass
Version: 2026.10.31
Summary: Molecular mass calculations
Home-page: https://www.cgohlke.com
Author: Christoph Gohlke
Author-email: cgohlke@cgohlke.com
License: BSD-3-Clause
Project-URL: Bug Tracker, https://github.com/cgohlke/molmass/issues
Project-URL: Source Code, https://github.com/cgohlke/molmass
Project-URL: Documentation, https://www.cgohlke.com/docs/molmass/
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.12
Description-Content-Type: text/x-rst
License-File: LICENSE
Provides-Extra: all
Requires-Dist: pandas; extra == "all"
Provides-Extra: gui
Requires-Dist: wxPython>=4.3; extra == "gui"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

Molecular mass calculations
===========================

Molmass is a Python library, console script, and web application to calculate
the molecular mass (average, nominal, and isotopic pure), the elemental
composition, and the mass distribution spectrum of a molecule given by its
chemical formula, relative element weights, or sequence.

Calculations are based on the isotopic composition of the elements. Mass
deficiency due to chemical bonding is not taken into account.

The library includes a database of physicochemical and descriptive properties
of the chemical elements.

:Author: `Christoph Gohlke <https://www.cgohlke.com>`_
:License: BSD-3-Clause
:Version: 2026.10.31
:DOI: `10.5281/zenodo.7135495 <https://doi.org/10.5281/zenodo.7135495>`_

Quickstart
----------

Install the molmass package and all dependencies from the
`Python Package Index <https://pypi.org/project/molmass/>`_::

    python -m pip install -U "molmass[all]"

See `Examples`_ and `Documentation <https://www.cgohlke.com/docs/molmass/>`_
for using the programming interface.

Print the console script usage::

    python -m molmass --help

Run the web application::

    python -m molmass --web

Try the `Molecular Mass Calculator <https://www.cgohlke.com/molmass/>`_ online.

Source code and support are available on
`GitHub <https://github.com/cgohlke/molmass>`_.

Requirements
------------

This revision was tested with the following requirements and dependencies
(other versions may work):

- `CPython <https://www.python.org>`_ 3.12.10, 3.13.16, 3.14.10, 3.15.2
- `Pandas <https://pypi.org/project/pandas/>`_ 3.1.0 (optional)
- `wxPython <https://pypi.org/project/wxPython/>`_ 4.3.2 (optional)

Revisions
---------

2026.10.31

- Update atomic weights and isotopic compositions (CIAAW 2024, AME2020).
- Update Dalton and particle masses to CODATA 2022.
- Reject charges inside brackets, for example [Na+] (#20, breaking).
- Reject negative and non-finite mass fractions (#22, breaking).
- Reject more invalid formulas and arguments (breaking).
- Make Element hashable and compare by identity (breaking).
- Compare Formula by Hill notation and support sum (breaking).
- Use abundance 1 for specified isotopes in Formula.isotope (breaking).
- Fix and improve from_fractions (breaking).
- Fix several formula parsing bugs.
- Fix Formula.isotope, arithmetic, spectrum, and concentration validation.
- Fix isotope, eleconfig, and ionenergy tables in elements.sqlite_script.
- Add density_unit argument to ppm conversion methods.
- Add Element.mass_uncertainty property.
- Fix and improve web and elements_gui applications.
- Improve docstrings and examples.
- Replace optparse with argparse.
- Run web application in http.server instead of Flask or CGI.

2026.8.15

- Add HTML application based on Pyodide.

2026.6.9

- Add convenience methods for concentration calculations.
- Use HTML Living Standard in web application.
- Drop support for Python 3.11, support Python 3.15.

2026.1.8

- …

Refer to the CHANGES file for older revisions.

Examples
--------

Calculate the molecular mass, elemental composition, and mass distribution of
a molecule from its chemical formula:

>>> from molmass import Formula
>>> f = Formula('C8H10N4O2')  # Caffeine
>>> f
Formula('C8H10N4O2')
>>> f.formula  # hill notation
'C8H10N4O2'
>>> f.empirical
'C4H5N2O'
>>> f.mass  # average mass
194.1909...
>>> f.nominal_mass  # == f.isotope.massnumber
194
>>> f.monoisotopic_mass  # == f.isotope.mass
194.0803...
>>> f.atoms
24
>>> f.charge
0
>>> f.composition().dataframe()
         Count  Relative mass  Fraction
Element...
C            8      96.085920  0.494801
H           10      10.079410  0.051905
N            4      56.026812  0.288514
O            2      31.998810  0.164780
>>> f.spectrum(min_intensity=0.01).dataframe()
             Relative mass  Fraction  Intensity %         m/z
Mass number...
194             194.080376  0.898828   100.000000  194.080376
195             195.082873  0.092625    10.305100  195.082873
196             196.084968  0.008022     0.892492  196.084968
197             197.087214  0.000500     0.055681  197.087214

Access physicochemical and descriptive properties of the chemical elements:

>>> from molmass import ELEMENTS, Element
>>> e = ELEMENTS['C']
>>> e
Element(
    6, 'C', 'Carbon',
    group=14, period=2, block='p', series=1,
    mass=12.01074, mass_uncertainty=0.001,
    eleneg=2.55, eleaffin=1.262118,
    covrad=0.77, atmrad=0.91, vdwrad=1.7,
    tboil=5100.0, tmelt=3825.0, density=3.51,
    eleconfig='[He] 2s2 2p2',
    oxistates='4*, 2, -4*',
    ionenergy=(
        11.2603, 24.383, 47.877, 64.492, 392.077,
        489.981,
    ),
    isotopes={
        12: Isotope(12.0, 0.9893, 12),
        13: Isotope(13.00335483534, 0.0107, 13),
    },
)
>>> e.number
6
>>> e.symbol
'C'
>>> e.name
'Carbon'
>>> e.description
'Carbon is a member of group 14 of the periodic table...'
>>> e.eleconfig
'[He] 2s2 2p2'
>>> e.eleconfig_dict
{(1, 's'): 2, (2, 's'): 2, (2, 'p'): 2}
>>> str(ELEMENTS[6])
'Carbon'
>>> len(ELEMENTS)
109
