Metadata-Version: 2.4
Name: finchge
Version: 1.0.1b3
Summary: FinchGE is a grammatical evolution library.
Author-email: Sudarshan Pant <sudarshan.pant@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/finchge/finchge
Project-URL: Documentation, https://finchge.readthedocs.io
Project-URL: Repository, https://github.com/finchge/finchge
Project-URL: Bug Reports, https://github.com/finchge/finchge/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tqdm>=4.67.1
Requires-Dist: diskcache>=5.6.3
Requires-Dist: requests>=2.32.5
Requires-Dist: tabulate>=0.9.0
Requires-Dist: matplotlib>=3.7.2
Requires-Dist: pandas>=2.3.3
Requires-Dist: scikit-learn>=1.7
Requires-Dist: typer>=0.21.1
Requires-Dist: PyYAML>=6.0
Requires-Dist: sympy>=1.12
Requires-Dist: cloudpickle>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: mkdocs>=1.6.1; extra == "dev"
Requires-Dist: mkdocs-autorefs>=1.4.3; extra == "dev"
Requires-Dist: mkdocs-material>=9.7.1; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.21.0; extra == "dev"
Requires-Dist: markdown-katex; extra == "dev"
Requires-Dist: pandas-stubs; extra == "dev"
Requires-Dist: types-tqdm; extra == "dev"
Requires-Dist: types-tabulate; extra == "dev"
Requires-Dist: black[jupyter]; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Provides-Extra: pytorch
Requires-Dist: torch>=2.8.0; extra == "pytorch"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.1; extra == "docs"
Requires-Dist: mkdocs-material>=9.7.1; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.21.0; extra == "docs"
Dynamic: license-file

# FinchGE: A Modular Grammatical Evolution Library

[![PyPI](https://img.shields.io/pypi/v/finchge?t=1234567890&color=blue)](https://pypi.org/project/finchge/)
[![Python](https://img.shields.io/pypi/pyversions/finchge?t=1234567890&color=blue)](https://pypi.org/project/finchge/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/readthedocs/finchge?color=blue)](https://finchge.readthedocs.io/)
[![Status](https://img.shields.io/badge/status-alpha-orange)](https://github.com/finchGE/finchge)
[![Tests](https://github.com/finchGE/finchge/actions/workflows/tests.yml/badge.svg)](https://github.com/finchGE/finchge/actions)


FinchGE is a modern, modular, and user-friendly Python library for Grammatical Evolution (GE) - a powerful evolutionary algorithm that uses formal grammars to evolve programs, expressions, and solutions.

## Features

- Define grammars using BNF-style syntax
- Supports standard genetic operations: mutation, crossover, selection
- Flexible fitness evaluation for any problem domain
- Modular and extensible design allowing conveniently plugin custom Algorithms and Operators
- Easy-to-read in-built logging and visualization
- Intuitive API with extensive documentation and examples


## Why finchGE


- Modular and extensible: Plug-and-play mutation,  election, fitness, and search strategies.
- Designed for research and industry: Convenient and flexible API for quicker implementation.

## Installation

```bash
# Basic installation
pip install finchge

# With optional dependencies
pip install finchge[pytorch]    # PyTorch support for using pytorch models (for HPO or NAS)
pip install finchge[all]        # All optional dependencies
```


## Quick Example

Using **finchGE** is straightforward.

Step 1. Define grammar

```python
grammar_file = "grammar.bnf"
grammar = Grammar.from_file(grammar_file)
```

Step 2. Define a Fitness Evaluator ; `fitness_evaluator`

```python

fitness_evaluator = FitnessEvaluator(
    fitness_functions=StringMatchFitness("hello"),
    mapper=GenotypeMapper(grammar=grammar)
)

```

Step 3. Create `GrammaticalEvolution` instance and run

```python
ge = GrammaticalEvolution(config=FinchConfig.default(),
                           grammar=grammar,
                           fitness_evaluator=fitness_evaluator)
ge.run()

```

For further details and more advanced usage, please check documentation
at [finchge.readthedocs.io](https://finchge.readthedocs.io/), including [Getting Started](https://finchge.readthedocs.io/latest/getting_started/), [API docReference](https://finchge.readthedocs.io/latest/api/) and [Examples](https://finchge.readthedocs.io/latest/examples/)




## Development Status
Note: This is version ```1.0.1-beta.3``` - an beta release. Expect breaking changes and bugs.

What to expect:

- Bugs and unexpected behavior
- Rapid API changes
- Frequent updates
- Limited test coverage (improving daily)

## Contributing

All contributions are welcome!

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Bug Reports and Feature Requests

Found a bug or have a feature request? Please [open an issue](https://github.com/finchge/finchge/issues) on GitHub.


## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
