mol-hume

Molecular descriptors computed in C++, verified column by column against RDKit and Mordred.

mol-hume emits 1,269 descriptors per molecule in about 285 microseconds, from a single call, plus a 2,048-bit ECFP alongside them. Of the descriptors, 1,109 reproduce ones that RDKit or Mordred already define, and 160 are new. Nothing is computed in Python.

pip install mol-hume

import molhume

X = molhume.featurize(["CCO", "CC(=O)Oc1ccccc1C(=O)O"], standardize="none")
# X -> (2, 3317) float64: 1,269 descriptors then 2,048 ECFP bits, ready for a model

xgboost.XGBRegressor().fit(X, y)

One array, not a tuple. The column names do not change from call to call, so returning them every time is something you would unpack and discard; ask for them when you need them, and they come back in the same order for the same flags:

df = pandas.DataFrame(X, columns=molhume.feature_names())

Pass the same flags to both and the names line up: feature_names(fingerprint=False) for the 1,269 descriptors alone, feature_names(columns=[...]) for a subset.

The one decision you have to make

standardize has no safe default, so leaving it unset warns once and tells you the options. Descriptors are computed on the graph you hand them: a salt, a tautomer and a charge state are three different molecules, and no library can guess which one you meant.

value	what it does
`"none"`	featurize exactly what you supplied
`"canonical"`	SMILES round-trip, nothing else
`"cleanup"`	RDKit `MolStandardize`: normalize, largest fragment, uncharge
a callable	your own `Mol -> Mol`

Passing "none" explicitly is a decision and is silent; omitting it is not, and warns.

Flags

flag	default	what it controls
`standardize`	`"none"` (warns if unset)	what molecule the numbers describe
`threads`	`0`	descriptor-block workers; `0` is one per hardware thread. Pass `1` if your own code is already parallel
`fingerprint`	`True`	append `fp_size` ECFP bit columns after the descriptors, so descriptor column indices never shift when the flag changes. Turning it off saves about 30 us/molecule that cannot be threaded
`fp_radius`	`3`	ECFP radius
`fp_size`	`2048`	ECFP bits
`additional_descriptors`	`True`	include the 160 descriptors that are ours rather than RDKit's or Mordred's. Selects what is returned, not what is computed
`columns`	`None`	emit only these names, in this order. Combined with `additional_descriptors` by AND
`optional`	`None`	expensive columns to compute. `AvgIpc` is on by default, `qed` off
`on_error`	`"nan"`	unparseable SMILES: `"nan"` keeps the row and fills it, so the output stays aligned with the input; `"raise"`; `"skip"` drops the row, so it does not
`dtype`	`float64`	`float32` halves the memory and is what the boosting libraries convert to internally anyway
`batch_size`	`4096`	rows per batch. Affects memory, not values

featurize also takes RDKit Mol objects instead of SMILES, which skips a parse.

molhume.feature_names(**flags) gives the names for any set of flags; molhume.ALL_COLUMNS is the full list, and molhume._additional.ADDITIONAL_COLUMNS the ones that are ours.

import mol_hume works too, and is the same module object — the distribution is mol-hume, and import mol-hume is a Python syntax error, not something a package can fix.

What "verified" means

Every column was compared against its upstream definition over a 42,000-molecule corpus spanning 1 to 64 heavy atoms:

167 of 186 RDKit columns and 412 of 968 Mordred columns are bit-identical.
99.99% (RDKit) and 99.23% (Mordred) of values agree to within 1e-9.

The remainder are deliberate, documented divergences, not unexplained differences: they are cases where the upstream definition depends on atom numbering or on a Kekule choice, and therefore has no single correct answer. Every one of them is listed with a measurement in METHODS.md.

The RDKit range

mol-hume requires rdkit>=2024.09.1,<2026.09, and this is a hard requirement rather than a preference. The library reads RDKit's MolPickler blob directly — a large part of where the speed comes from — and that format is explicitly not a stable API. Outside the range that has been measured, mol-hume refuses to import rather than misparse a molecule into wrong numbers with no symptom.

Within the range, the pickle format is checked rather than assumed: RDKit 2026.03 writes a different format version from 2025.09, and it is accepted because 4,000 corpus molecules pickle to bytes that differ only in the version triple, and all 1,269 columns over 8,000 molecules come out bit-identical. Widening it for a future release is one command — tools/check_rdkit_release.py — plus, if the blobs really changed, work on the reader. See MAINTENANCE.md.

Within that range, values are quoted against RDKit 2025.9.2 specifically. RDKit's perceived atom and bond properties drift across releases, so a different RDKit inside the range can still move values in the last digits.

Why 1,269 and not 1,539

The implemented set was 1,539 columns. Pairs that carry the same information were removed by a greedy cover in ascending compute cost: a column is dropped when some cheaper surviving column predicts it at |Spearman| >= 0.99 on ranks, and that has to hold in every one of five heavy-atom strata, not just on the pooled corpus, so a correlation that only exists because small and large molecules sit at opposite ends of both scales does not count. Columns that are NaN more than half the time, or that take one value for 99.9% of molecules, are dropped as unusable. What survives is 1,269.

Platforms

Wheels are built for the platforms RDKit itself ships, since a mol-hume wheel for a platform with no RDKit wheel could not be imported:

	CPython 3.11 - 3.14
Linux x86_64, aarch64	manylinux_2_28
macOS arm64	11.0+
macOS x86_64	10.15+, needs `rdkit<=2025.9.2` (RDKit dropped Intel Mac after that)
Windows x86_64	MSVC

No musl, no 32-bit, no PyPy — RDKit publishes none of those. The extension links only the C++ runtime: no BLAS, no RDKit library, and no NumPy ABI, so one wheel works across NumPy 1.x and 2.x.

Values are not bit-identical across architectures

This matters if you are comparing outputs between machines, and not at all if you are fitting a model. The exactness numbers above were measured on macOS arm64 with clang. The same source on x86-64 moves the last bits: 594 of the 1,269 columns under gcc, 595 under MSVC, with a maximum disagreement of 1.1e-14 of each column's range. Nothing structural changes — the NaN pattern is identical on all three.

That is not a bug that a build flag removes. The library reproduces upstream floating-point behavior, so a different libm's log and a different FMA decision are part of the result. CI measures this on every platform (tools/platform_drift.py) and the test suite asserts a bound on it, exactly rather than approximately on the reference platform.

Beware per-value relative error when you compare: several columns are differences that cancel to near zero (the centered autocorrelations, Cyclicity, DeltaMean), where a last-bit wobble reads as a relative error of 27. Compare against each column's range.

Development

uv pip install -e . --python .venv/bin/python -c constraints.txt
.venv/bin/python -m pytest tests/

The pinned RDKit in constraints.txt is the oracle every exactness claim is measured against — install with -c constraints.txt or a bare editable install will silently upgrade it. tests/ runs in seconds against a committed fixture; the full exactness verifications against RDKit and Mordred are the root-level verify_*.py, which need the corpus and a second environment. See tests/README.md.

Acknowledgments

mol-hume reproduces descriptors first defined and published by two projects, and would not exist without either:

RDKit — Greg Landrum and contributors. RDKit parses the molecule and supplies every perceived atom and bond property this library computes from, and 186 of the emitted columns reproduce RDKit descriptor definitions. Several parameter tables here are derived from published RDKit values, including the Crippen logP/MR atom-type contributions and the Hall-Kier alpha table. BSD 3-Clause.
Mordred — Hirotomo Moriwaki et al., J. Cheminform. 10, 4 (2018). 968 of the emitted columns reproduce Mordred definitions. BSD 3-Clause.

Where this library's values differ from either, the difference is deliberate and documented: those are cases where the upstream definition depends on atom numbering or on a Kekule choice and so has no single correct answer. Every one is listed with a measurement in METHODS.md.

License

BSD 3-Clause. See LICENSE.

Development Status
- 4 - Beta
Intended Audience
- Science/Research
Programming Language
- C++
- Python :: 3
Topic
- Scientific/Engineering :: Chemistry

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mol_hume-0.1.0.tar.gz (468.6 kB view details)

Uploaded Sep 1, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mol_hume-0.1.0-cp314-cp314-win_amd64.whl (651.3 kB view details)

Uploaded Sep 1, 2026 CPython 3.14Windows x86-64

mol_hume-0.1.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (518.5 kB view details)

Uploaded Sep 1, 2026 CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mol_hume-0.1.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (481.6 kB view details)

Uploaded Sep 1, 2026 CPython 3.14manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

mol_hume-0.1.0-cp314-cp314-macosx_11_0_arm64.whl (441.6 kB view details)

Uploaded Sep 1, 2026 CPython 3.14macOS 11.0+ ARM64

mol_hume-0.1.0-cp314-cp314-macosx_10_15_x86_64.whl (487.7 kB view details)

Uploaded Sep 1, 2026 CPython 3.14macOS 10.15+ x86-64

mol_hume-0.1.0-cp313-cp313-win_amd64.whl (627.9 kB view details)

Uploaded Sep 1, 2026 CPython 3.13Windows x86-64

mol_hume-0.1.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (517.9 kB view details)

Uploaded Sep 1, 2026 CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mol_hume-0.1.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (481.0 kB view details)

Uploaded Sep 1, 2026 CPython 3.13manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

mol_hume-0.1.0-cp313-cp313-macosx_11_0_arm64.whl (441.3 kB view details)

Uploaded Sep 1, 2026 CPython 3.13macOS 11.0+ ARM64

mol_hume-0.1.0-cp313-cp313-macosx_10_15_x86_64.whl (487.7 kB view details)

Uploaded Sep 1, 2026 CPython 3.13macOS 10.15+ x86-64

mol_hume-0.1.0-cp312-cp312-win_amd64.whl (627.8 kB view details)

Uploaded Sep 1, 2026 CPython 3.12Windows x86-64

mol_hume-0.1.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (517.9 kB view details)

Uploaded Sep 1, 2026 CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mol_hume-0.1.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (480.9 kB view details)

Uploaded Sep 1, 2026 CPython 3.12manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

mol_hume-0.1.0-cp312-cp312-macosx_11_0_arm64.whl (441.3 kB view details)

Uploaded Sep 1, 2026 CPython 3.12macOS 11.0+ ARM64

mol_hume-0.1.0-cp312-cp312-macosx_10_15_x86_64.whl (487.7 kB view details)

Uploaded Sep 1, 2026 CPython 3.12macOS 10.15+ x86-64

mol_hume-0.1.0-cp311-cp311-win_amd64.whl (624.0 kB view details)

Uploaded Sep 1, 2026 CPython 3.11Windows x86-64

mol_hume-0.1.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (517.9 kB view details)

Uploaded Sep 1, 2026 CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

mol_hume-0.1.0-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (480.7 kB view details)

Uploaded Sep 1, 2026 CPython 3.11manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

mol_hume-0.1.0-cp311-cp311-macosx_11_0_arm64.whl (439.5 kB view details)

Uploaded Sep 1, 2026 CPython 3.11macOS 11.0+ ARM64

mol_hume-0.1.0-cp311-cp311-macosx_10_15_x86_64.whl (485.6 kB view details)

Uploaded Sep 1, 2026 CPython 3.11macOS 10.15+ x86-64

File details

Details for the file mol_hume-0.1.0.tar.gz.

File metadata

Download URL: mol_hume-0.1.0.tar.gz
Upload date: Sep 1, 2026
Size: 468.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mol_hume-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`9268fa9f5fa662dec06bb6865663b033ebb092b02d9abc560694e94e6c610c0b`
MD5	`24f82fd409e0dc77f933ebbb5cfb29fd`
BLAKE2b-256	`eb101ec4b0214d02a9aae4e7b7fdaaa5a429485d01d3dbecd07d616182e14019`

Algorithm	Hash digest
SHA256	`65fc2f2e534c5f883b579584a7b5b4a07a331058357b3664caae360a412e579e`
MD5	`dfd4b2282a55379c31cf4a6204b345ff`
BLAKE2b-256	`9b589564d5d533a37e06a8665ca71263aa5e373b4e2cdc3e1f19cd06b5c430e3`

Algorithm	Hash digest
SHA256	`504f9169c03d30f13bfe4bfc67b93c57d1a66f54c08ad72bfda08b67995ebdb5`
MD5	`83467dd61cd7a23b30fa0ed0456c87f7`
BLAKE2b-256	`4103bd4e209287ad5ec13815f722176d811750d4bacb0c37737f8e523d5bd490`

Algorithm	Hash digest
SHA256	`365c0b4d3431f42dbc6c349165308c270a72d265547aa7050d96e849d5b20e09`
MD5	`deaf60ca0aa8c2b9c87dc569b612e86c`
BLAKE2b-256	`458df63fb5db6f8cdc5ace9312e821abd7e65af1890d53465e4b1a7cd34f9a78`

Algorithm	Hash digest
SHA256	`7dc3fce41f55b414c6832be8c54179bccce210d125feb09058af75df149df26e`
MD5	`44e2068296bf1513f15bd2dc6c794af8`
BLAKE2b-256	`29e511dafcd07eccc69b4fad5f87123e2522855e77e8d489b7fe474907d0482d`

Algorithm	Hash digest
SHA256	`24c559bf66848d4d71d0cbe793f66c066d15dce3cc00d037153ec1a580ded62e`
MD5	`9629cf888c2a5d91db213acfc5744e8e`
BLAKE2b-256	`fab3c552bd5cb6eb8344c914efa01019bcd7e92433ad1f6873fade91358e6f22`

Algorithm	Hash digest
SHA256	`89c390cca86f930bc9d6c22653cd7ba3720e028b0c793180ee176c0d571fbd23`
MD5	`789d797d3e251709a393ff7830c18e3a`
BLAKE2b-256	`3b9d63dcce8e8252cd389b6b74d16be6c1d658bcd445aa685045fdfa917d5cd7`

Algorithm	Hash digest
SHA256	`12fea85858beed14bb21296ba3cfcf18b8e623231d357921ede5de08ad832a1f`
MD5	`e34cded38b2a0fc932bdd98b0746e852`
BLAKE2b-256	`03d9ec7716794e1430c8c91ac2f6afc0646fd28b2e51bdd54cc66b94f823cf10`

Algorithm	Hash digest
SHA256	`92659311bd06fe145ddccce519f9b8acd17130ee52f2154c5e6848a3be49f7db`
MD5	`4a3f86136f624587ca6423c12cf72cf2`
BLAKE2b-256	`3a256fc22a06d2cd924976742e6a0ce0da16a61912e7e1032748f030c09c2f06`

Algorithm	Hash digest
SHA256	`7212de44cd89adc626841760a37f469a201e6fc3778376951acae81dd1bbf3f0`
MD5	`02e7a77cfb76dadc9248fab6b046a5af`
BLAKE2b-256	`0f33f843c334bb9310719a0850cb08c1ca3986f63243ed19d4ca490feb9844e8`

Algorithm	Hash digest
SHA256	`36533d7a5aeb16dfef6b98432b0b8624d455fde6129976e64c911371e61526a6`
MD5	`f30e7e1a6b77329f5aa18f0632eb56b3`
BLAKE2b-256	`3d540df559b1e83c9e5ee16d9be53c1101ea3303531e8720dab2d9401ca84852`

Algorithm	Hash digest
SHA256	`7af3fb9b7f02c468f4b2b88564a8fcaefadf2e135c083c6631c8042c70527c70`
MD5	`4595d6eeeb0b88c23af16b30b0995c8a`
BLAKE2b-256	`ae637545ca05b995fbfd4d4eeeba3226befb5eb9012787c746895c73f3c2913b`

Algorithm	Hash digest
SHA256	`584980c27a5ff78cf380c662ba3c32a2f78db0da18fbc5b7271fb994faeb60a1`
MD5	`5289ed9456a6efc1f66830a7197d0b46`
BLAKE2b-256	`e1d03aacdd7c935ffe291ec4078ab85188655ff6a7200dbb7e394553282179c8`

Algorithm	Hash digest
SHA256	`7efb9472ca1f1f94299861cc4cdc59746df375ece267141a16bbebcaf11b95ba`
MD5	`4abfe6d963fc7161005455043a3c0901`
BLAKE2b-256	`b9c2ec0ac8bdf96aa901790b411fb7823c18ecb223e94e764e71dde2314ad536`

Algorithm	Hash digest
SHA256	`da213f14830d3f32fa4745a19165bb16c1d6a11d58131bea364fb273ec359682`
MD5	`85fa3cf58b3bb05a5a60ced46e72d218`
BLAKE2b-256	`ac98b11d09c532fd1609b66c1fdae009f97adbf53b14ce865fa5eb6d0b3b9804`

Algorithm	Hash digest
SHA256	`a254e7a3c23b4b5e345348e5c34a9bfe9c4664a0153c6adaee9804cbecc869f8`
MD5	`7103909780b3c21812b991c496022d8b`
BLAKE2b-256	`b6f82e70407aeb15c02592cb452d9870cd794a31c7ea8d3fb795786ea5a714d8`

Algorithm	Hash digest
SHA256	`c95a5dfee0d73fa0dad69aa63489d16297e6d281b98858173b49ea216d87023e`
MD5	`f2a5119d7376563ac93b753134b327fd`
BLAKE2b-256	`7e4849781a4f129657b9eccb539607ef477749433c4c9ee1547cf8ccaf35ddce`

Algorithm	Hash digest
SHA256	`7190960981f13ae48372a4a553bf4d28bbf603f428048212294877e9972de003`
MD5	`8fbf0212aaf97cec9746abd97c2913c5`
BLAKE2b-256	`dde3596a79b2ce0e8d4ae4b71966a741e862ab11d7ce121c2725f62e622178e5`

Algorithm	Hash digest
SHA256	`7944c745530ea19e6c294b58e04421d25e05a62c85dc0f9ba1e75e6a3401f114`
MD5	`2696e9ed5ef55e106bb608c99754782b`
BLAKE2b-256	`2643854809ed1461f148409140cf6aca9dbac24c932aea5cf003a325052be2ec`

Algorithm	Hash digest
SHA256	`19ceaf8c55a5805c3d0367d551255a95b23b3ab1bae1269288df4fa0e5ae7886`
MD5	`afca4ea1f0de7fa5b105b68bda79e1ce`
BLAKE2b-256	`c0349ed69c30897e5c00eb61d1155031ee0be732fe6ed22b402aae80a52fd30b`

Algorithm	Hash digest
SHA256	`ecd859127dede39161f1f869e4ad9cca897f0e1991416c8a8fe375345af6e72f`
MD5	`e729f227c8dff300d9157a78a67fd5f3`
BLAKE2b-256	`a9bfa4c86d4186c4516cd43d7813ae0ce0bfb6b311b5a92929e33140268505df`

mol-hume 0.1.0

mol-hume

The one decision you have to make

Flags

What "verified" means

The RDKit range

Why 1,269 and not 1,539

Platforms

Values are not bit-identical across architectures

Development

Acknowledgments

License

Key dates

1 maintainer

Credits

License expression

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details