mineral-database

SQLite database of 94+ mineral presets with CDL definitions, crystal system data, and gemmological properties.

pip install mineral-database

Functions

# get_preset(name: str) → MineralPreset | None

Get a mineral preset by name (case-insensitive).

from mineral_database import get_preset

preset = get_preset("quartz")
if preset:
    print(preset.name)         # "Quartz"
    print(preset.cdl)          # "trigonal[-3m]:{10-10}@1.0 + ..."
    print(preset.system)       # "trigonal"
    print(preset.hardness)     # 7.0
    print(preset.ri_range)     # (1.544, 1.553)

Parameters:

name - Mineral name (case-insensitive)

Returns: MineralPreset or None if not found

# list_presets() → list[str]

List all available preset names.

from mineral_database import list_presets

names = list_presets()
print(len(names))  # 94
print(names[:5])   # ['Alexandrite', 'Almandine', 'Amazonite', ...]

# search(query: str, limit: int = 10) → list[MineralPreset]

Search presets by name, formula, or properties.

from mineral_database import search

# Search by name
results = search("beryl")
for r in results:
    print(r.name)  # Beryl, Emerald, Aquamarine, ...

# Search by chemical formula
results = search("SiO2")

# Search by crystal system
results = search("cubic")

# get_by_system(system: str) → list[MineralPreset]

Get all presets for a specific crystal system.

from mineral_database import get_by_system

cubic_minerals = get_by_system("cubic")
print(len(cubic_minerals))  # 18

# Valid systems: cubic, hexagonal, trigonal, tetragonal,
#                orthorhombic, monoclinic, triclinic

# get_by_hardness(min_h: float, max_h: float) → list[MineralPreset]

Get presets within a hardness range.

from mineral_database import get_by_hardness

# Get gems suitable for rings (hardness 7+)
durable = get_by_hardness(7.0, 10.0)
for m in durable:
    print(f"{m.name}: {m.hardness}")

# get_by_ri(ri: float, tolerance: float = 0.01) → list[MineralPreset]

Find minerals matching a measured refractive index.

from mineral_database import get_by_ri

# Find minerals with RI around 1.54
matches = get_by_ri(1.54, tolerance=0.01)
for m in matches:
    print(f"{m.name}: {m.ri_range}")

Classes

`MineralPreset`

Complete mineral data including CDL and gemmological properties.

Attribute	Type	Description
`name`	`str`	Mineral name
`cdl`	`str`	CDL expression
`system`	`str`	Crystal system
`point_group`	`str`	Point group symbol
`formula`	`str \| None`	Chemical formula
`hardness`	`float \| None`	Mohs hardness
`specific_gravity`	`tuple[float, float] \| None`	SG range
`ri_range`	`tuple[float, float] \| None`	Refractive index range
`birefringence`	`float \| None`	Maximum birefringence
`optic_sign`	`str \| None`	"+" or "-" or None (isotropic)
`optic_character`	`str \| None`	"uniaxial" or "biaxial" or None
`dispersion`	`float \| None`	Dispersion value
`colors`	`list[str]`	Common colors
`cleavage`	`str \| None`	Cleavage description
`varieties`	`list[str]`	Named varieties

Methods

# Check if preset matches identification criteria
preset.matches_ri(1.544)           # True if RI in range
preset.matches_sg(2.65)            # True if SG in range
preset.matches_hardness(7.0)       # True if hardness matches

# Export to different formats
preset.to_dict()                   # Dictionary representation
preset.to_json()                   # JSON string

Database Information

# get_db_info() → dict

Get database metadata.

from mineral_database import get_db_info

info = get_db_info()
print(info)
# {
#   'version': '1.0.0',
#   'preset_count': 94,
#   'systems': {'cubic': 18, 'hexagonal': 12, ...},
#   'last_updated': '2025-01-15'
# }

Custom Database

Load a custom SQLite database with additional presets:

from mineral_database import MineralDatabase

# Load custom database
db = MineralDatabase("/path/to/custom.db")

# Use same API
preset = db.get_preset("custom_mineral")
all_presets = db.list_presets()

Included Presets

The database includes 94 mineral presets organized by crystal system:

Cubic (18)

Diamond, Spinel, Garnet group, Pyrite, Fluorite...

Hexagonal (12)

Beryl varieties, Apatite, Zincite...

Trigonal (15)

Quartz varieties, Corundum, Tourmaline, Calcite...

Tetragonal (8)

Zircon, Rutile, Cassiterite, Vesuvianite...

Orthorhombic (14)

Topaz, Peridot, Chrysoberyl, Tanzanite...

Monoclinic (12)

Orthoclase, Jadeite, Spodumene, Malachite...