# random-formula

**Repository Path**: ms2lab/random-formula

## Basic Information

- **Project Name**: random-formula
- **Description**: 随机产生化学式
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-17
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Random Formula

Generate random chemical formulas with customizable parameters.

## Description

Random Formula is a Python package that generates random chemical formulas according to user-specified parameters. It supports generating formulas from anonymous formulas (like "A1-20B1-20C1-20") or randomly generating elements and atom counts.

## Installation

### Using uv (Local Development Install)

```bash
uv pip install -e .
```

### Using pip (Local Development Install)

```bash
pip install -e .
```

### Install with Development Dependencies

```bash
# Using uv
uv pip install -e .[dev]

# Using pip
pip install -e .[dev]
```

## Usage

### Command Line Interface

```bash
random-formula -n 5
```

This will generate 5 random chemical formulas with default parameters.

### CLI Options

```
-h, --help            show this help message and exit
--anoumous-formula ANOUMOUS_FORMULA
                        Anonymous formula, e.g., A1-20B1-20C1-20
-n N                  Number of formulas to generate (default: 1)
--min-ns MIN_NS, --min-num-species MIN_NS
                        Minimum number of species (default: 2)
--max-ns MAX_NS, --max-num-species MAX_NS
                        Maximum number of species (default: 4)
--max-z MAX_Z         Maximum atomic number (default: 100)
--min-na MIN_NA, --min-num-atoms MIN_NA
                        Minimum number of atoms
--max-na MAX_NA, --max-num-atoms MAX_NA
                        Maximum number of atoms (default: 60)
--na-distribution {MP20250925,MP250925,uniform}
                        Number of atoms distribution (default: MP250925)
--exclude [EXCLUDE ...]
                        Exclude elements by symbol or atomic number
```

### Examples

#### Generate 10 formulas with default parameters

```bash
random-formula -n 10
```

#### Generate formulas from an anonymous formula

```bash
random-formula --anoumous-formula "A1-5B1-3C1-2" -n 5
```

#### Exclude specific elements

```bash
random-formula --exclude O C H -n 5
```

#### Use uniform distribution for number of atoms

```bash
random-formula --na-distribution uniform -n 5
```

## API Usage

### Python Module

```python
from random_formula.main import (
    get_available_elements,
    generate_from_anonymous_formula,
    generate_from_random_species
)
from random_formula.distribution import get_distribution

# Get available elements
available_elements = get_available_elements(max_z=100, exclude=["O", "C"])

# Get distribution for number of atoms
distribution = get_distribution("MP250925", min_na=1, max_na=60)

total_atoms = distribution.sample(k=1)[0]

# Generate formula from anonymous formula
formula1 = generate_from_anonymous_formula(
    "A1-5B1-3C1-2",
    total_atoms,
    available_elements
)

# Generate formula from random species
formula2 = generate_from_random_species(
    min_ns=2,
    max_ns=4,
    total_atoms=total_atoms,
    available_elements=available_elements
)
```

## Development

### Install development dependencies

```bash
uv install -e .[dev]
```

### Run tests

```bash
python -m pytest tests/ -v
```

### Format code

```bash
ruff format
```

### Check code quality

```bash
ruff check
```

## License

MIT