Metadata-Version: 2.4
Name: chemql-python
Version: 0.2.0
Summary: A chemistry-focused query language and REPL
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: prompt_toolkit>=3.0
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Dynamic: license-file

# ChemQL

![ChemQL logo](logo.png)

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`:

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

This installs the Python package and the `chemql` CLI:

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

Start the interactive REPL with:

```bash
python -m chemql
```

You will see the interactive prompt:

```text
>>> 
```

Type:

```text
help
```

or:

```text
?
```

to display the built-in help.

## Command-line usage

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

```bash
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:

```python
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

```text
search elements
search molecules
search reactions
```

### Search with filters

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

### Sort, limit, and count

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

### Return selected fields

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

### Set the current source

```text
source elements
source molecules
source reactions
```

### List available keys

```text
list all
```

## Convenience lookup commands

```text
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:

```text
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 //reversible
balance O2 + H2 <-> H2O //irreversible
```

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 optional `//reversible` and `//irreversible` annotations set the returned
reaction direction; without an annotation, `->` is irreversible and `<->` is
reversible. The function API is
`balance_stoichiometry(reactants, products, reversible=None)`.

## Operators

ChemQL supports these comparison operators:

- `=`
- `>`
- `<`
- `>=`
- `<=`
- `like`
- `like!`
- `has`

Boolean logic:

```text
and
or
```

Parentheses may be used to group expressions.

## Result controls

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

## General commands

```text
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:

```text
[x = 10]
[print(x)]
```

Conditional and loop blocks are also supported:

```text
[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:

```text
[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:

```text
search elements \
name = "Hydrogen"
```

This is treated as:

```text
search elements name = "Hydrogen"
```

## Examples

```text
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

```text
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](https://github.com/rakibulofficial1017).
Source code: [rakibulofficial1017/ChemQL](https://github.com/rakibulofficial1017/ChemQL).
