ChemQL

ChemQL is a chemistry-focused query language and REPL for exploring element, molecule, and reaction datasets. It lets you search the built-in chemistry data, filter results with expressions, set reaction conditions, and combine queries with small Python snippets when needed.

What ChemQL does

ChemQL supports:

• Searching the built-in elements, molecules, and reactions datasets
• Filtering by field, comparison operator, pattern matching, and boolean logic
• Quick lookup commands like findel, findmol, and findre
• Reaction setup with temperature, pressure, and catalyst configuration
• Running reactions with react
• Embedding Python in [ ... ] blocks and templates in {{ ... }}
• Running from a terminal REPL or executing a command/file from the shell

Install the library

Install from this chemql/ directory, which contains pyproject.toml:

cd /path/to/ChemQL/Language/chemql
python -m pip install -e ".[test]"

This installs the Python package and the chemql CLI:

chemql -c "search elements name = 'Hydrogen'"

Start the interactive REPL with:

python -m chemql

You will see the interactive prompt:

>>> 

Type:

help

or:

?

to display the built-in help.

Command-line usage

You can also execute a single ChemQL command or a file:

chemql -c 'search elements name = "Hydrogen"'
chemql -f examples/script.cql

The Python package is chemql. Its query engine, chemistry types, and bundled datasets can be imported directly:

from chemql import balance_stoichiometry, execute_query_text

result = execute_query_text('search elements name = "Hydrogen"')
reaction = balance_stoichiometry(["O2", "H2"], ["H2O"], reversible=True)
print(reaction)

Core query syntax

Search a dataset

search elements
search molecules
search reactions

Search with filters

search elements atomic_number > 10 and atomic_number < 20
search molecules name like "*water*"
search reactions reaction_type = "combustion"

Sort, limit, and count

search molecules sort molecular_weight desc
search molecules limit 10
search molecules count

Return selected fields

search molecules molecular_weight < 20 return name formula molecular_weight
search reactions reversible = true return name conditions

Set the current source

source elements
source molecules
source reactions

List available keys

list all

Convenience lookup commands

findel "He"
findel "Hydrogen"

findmol "H2O"
findmol "Water"

findre "Haber process"
findre "RHEA:10000" return name equation source

Reactions

Set reaction conditions before running a reaction:

set temperature 723K
set temperature standard
set pressure 20265000pa
set pressure room
set catalysts iron zinc
add catalyst "Vanadium oxide"
remove catalyst "Vanadium oxide"
conditions
react N2 3H2
balance O2 + H2 -> H2O
balance O2 + H2 <-> H2O

Temperature accepts C, F, or K; pressure accepts Pa, N/m^2, Nm^-2, bar, or atm. The keywords standard and room are also accepted.

balance accepts chemical formulas on each side, separated by +. It returns a Reaction with the smallest positive integer stoichiometric coefficients. The arrow determines reaction direction: -> is irreversible and <-> is reversible. // begins a comment, as it does elsewhere in ChemQL. The function API is balance_stoichiometry(reactants, products, reversible=None).

Operators

ChemQL supports these comparison operators:

• =
• >
• <
• >=
• <=
• like
• like!
• has

Boolean logic:

and
or

Parentheses may be used to group expressions.

Result controls

search molecules first
search molecules last
search molecules sort atomic_number desc limit 5
search molecules count

General commands

list all
view
clear
dump my_session.txt
help
exit

view opens the periodic table in a browser. dump writes recent command history to a file.

Hybrid Python mode

ChemQL can be mixed with Python inside square-bracket blocks:

[x = 10]
[print(x)]

Conditional and loop blocks are also supported:

[for x in range(3)]
[print(x)]
[endblock]

[if x > 0]
[print("positive")]
[else]
[print("not positive")]
[endblock]

Embedded ChemQL queries can also be used with double-brace syntax. This executes a query and uses the result as a value in the surrounding Python:

[print({{ search elements number = 1 }})]
[for i in {{search elements number <= 10}}]
    [print(i.name)]
[endblock]

The {{ ... }} form is a convenient way to make a query return actual data to Python, rather than only writing a plain query line.

Line continuation

If a line ends with \, it continues onto the next line:

search elements \
name = "Hydrogen"

This is treated as:

search elements name = "Hydrogen"

Examples

search elements name = "Hydrogen"
findel "He"
findmol "H2O"

search molecules molecular_weight < 20 \
return name formula molecular_weight

search elements atomic_number > 10 \
and atomic_number < 20 \
sort atomic_number desc \
limit 5

search molecules count

Repository layout

chemql/
├── pyproject.toml
├── src/
│   └── chemql/
│       ├── __init__.py
│       ├── __main__.py
│       ├── data/
│       └── html/
├── tests/
├── scripts/
└── examples/

The installable package contains the language implementation and its bundled chemical datasets.

Created by Mohammad Rakibul Islam. Source code: rakibulofficial1017/ChemQL.