# PyCave
PyCave allows you to run traditional machine learning models on CPU, GPU, and even on multiple
nodes. All models are implemented in [PyTorch](https://pytorch.org/) and provide an `Estimator` API
that is fully compatible with [scikit-learn](https://scikit-learn.org/stable/).
For Gaussian mixture model, PyCave allows for 100x speed ups when using a GPU and enables to train
on markedly larger datasets via mini-batch training. The full suite of benchmarks run to compare
PyCave models against scikit-learn models is available on the
[documentation website](https://pycave.borchero.com/sites/benchmark.html).
_PyCave version 3 is a complete rewrite of PyCave which is tested much more rigorously, depends on
well-maintained libraries and is tuned for better performance. While you are, thus, highly
encouraged to upgrade, refer to [pycave-v2.borchero.com](https://pycave-v2.borchero.com) for
documentation on PyCave 2._
## Features
- Support for GPU and multi-node training by implementing models in PyTorch and relying on
[PyTorch Lightning](https://www.pytorchlightning.ai/)
- Mini-batch training for all models such that they can be used on huge datasets
- Well-structured implementation of models
- High-level `Estimator` API allows for easy usage such that models feel and behave like in
scikit-learn
- Medium-level `LightingModule` implements the training algorithm
- Low-level PyTorch `Module` manages the model parameters
## Installation
PyCave is available via `pip`:
```bash
pip install pycave
```
If you are using [Poetry](https://python-poetry.org/):
```bash
poetry add pycave
```
## Usage
If you've ever used scikit-learn, you'll feel right at home when using PyCave. First, let's create
some artificial data to work with:
```python
import torch
X = torch.cat([
torch.randn(10000, 8) - 5,
torch.randn(10000, 8),
torch.randn(10000, 8) + 5,
])
```
This dataset consists of three clusters with 8-dimensional datapoints. If you want to fit a K-Means
model, to find the clusters' centroids, it's as easy as:
```python
from pycave.clustering import KMeans
estimator = KMeans(3)
estimator.fit(X)
# Once the estimator is fitted, it provides various properties. One of them is
# the `model_` property which yields the PyTorch module with the fitted parameters.
print("Centroids are:")
print(estimator.model_.centroids)
```
Due to the high-level estimator API, the usage for all machine learning models is similar. The API
documentation provides more detailed information about parameters that can be passed to estimators
and which methods are available.
### GPU and Multi-Node training
For GPU- and multi-node training, PyCave leverages PyTorch Lightning. The hardware that training
runs on is determined by the
[Trainer](https://pytorch-lightning.readthedocs.io/en/latest/api/pytorch_lightning.trainer.trainer.html#pytorch_lightning.trainer.trainer.Trainer)
class. It's
[**init**](https://pytorch-lightning.readthedocs.io/en/latest/api/pytorch_lightning.trainer.trainer.html#pytorch_lightning.trainer.trainer.Trainer.__init__)
method provides various configuration options.
If you want to run K-Means with a GPU, you can pass the options `accelerator='gpu'` and `devices=1`
to the estimator's initializer:
```python
estimator = KMeans(3, trainer_params=dict(accelerator='gpu', devices=1))
```
Similarly, if you want to train on 4 nodes simultaneously where each node has one GPU available,
you can specify this as follows:
```python
estimator = KMeans(3, trainer_params=dict(num_nodes=4, accelerator='gpu', devices=1))
```
In fact, **you do not need to change anything else in your code**.
### Implemented Models
Currently, PyCave implements three different models:
- [GaussianMixture](https://pycave.borchero.com/sites/generated/bayes/gmm/pycave.bayes.GaussianMixture.html)
- [MarkovChain](https://pycave.borchero.com/sites/generated/bayes/markov_chain/pycave.bayes.MarkovChain.html)
- [K-Means](https://pycave.borchero.com/sites/generated/clustering/kmeans/pycave.clustering.KMeans.html)
## License
PyCave is licensed under the [MIT License](https://github.com/borchero/pycave/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/borchero/pycave",
"name": "pycave",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<3.11",
"maintainer_email": "",
"keywords": "",
"author": "Oliver Borchert",
"author_email": "me@borchero.com",
"download_url": "https://files.pythonhosted.org/packages/b3/f8/b60008b98a741c3576d2ca990848085d59defe6bca9bc71373fdb864ad1f/pycave-3.2.1.tar.gz",
"platform": null,
"description": "# PyCave\n\n\n\n\nPyCave allows you to run traditional machine learning models on CPU, GPU, and even on multiple\nnodes. All models are implemented in [PyTorch](https://pytorch.org/) and provide an `Estimator` API\nthat is fully compatible with [scikit-learn](https://scikit-learn.org/stable/).\n\nFor Gaussian mixture model, PyCave allows for 100x speed ups when using a GPU and enables to train\non markedly larger datasets via mini-batch training. The full suite of benchmarks run to compare\nPyCave models against scikit-learn models is available on the\n[documentation website](https://pycave.borchero.com/sites/benchmark.html).\n\n_PyCave version 3 is a complete rewrite of PyCave which is tested much more rigorously, depends on\nwell-maintained libraries and is tuned for better performance. While you are, thus, highly\nencouraged to upgrade, refer to [pycave-v2.borchero.com](https://pycave-v2.borchero.com) for\ndocumentation on PyCave 2._\n\n## Features\n\n- Support for GPU and multi-node training by implementing models in PyTorch and relying on\n [PyTorch Lightning](https://www.pytorchlightning.ai/)\n- Mini-batch training for all models such that they can be used on huge datasets\n- Well-structured implementation of models\n\n - High-level `Estimator` API allows for easy usage such that models feel and behave like in\n scikit-learn\n - Medium-level `LightingModule` implements the training algorithm\n - Low-level PyTorch `Module` manages the model parameters\n\n## Installation\n\nPyCave is available via `pip`:\n\n```bash\npip install pycave\n```\n\nIf you are using [Poetry](https://python-poetry.org/):\n\n```bash\npoetry add pycave\n```\n\n## Usage\n\nIf you've ever used scikit-learn, you'll feel right at home when using PyCave. First, let's create\nsome artificial data to work with:\n\n```python\nimport torch\n\nX = torch.cat([\n torch.randn(10000, 8) - 5,\n torch.randn(10000, 8),\n torch.randn(10000, 8) + 5,\n])\n```\n\nThis dataset consists of three clusters with 8-dimensional datapoints. If you want to fit a K-Means\nmodel, to find the clusters' centroids, it's as easy as:\n\n```python\nfrom pycave.clustering import KMeans\n\nestimator = KMeans(3)\nestimator.fit(X)\n\n# Once the estimator is fitted, it provides various properties. One of them is\n# the `model_` property which yields the PyTorch module with the fitted parameters.\nprint(\"Centroids are:\")\nprint(estimator.model_.centroids)\n```\n\nDue to the high-level estimator API, the usage for all machine learning models is similar. The API\ndocumentation provides more detailed information about parameters that can be passed to estimators\nand which methods are available.\n\n### GPU and Multi-Node training\n\nFor GPU- and multi-node training, PyCave leverages PyTorch Lightning. The hardware that training\nruns on is determined by the\n[Trainer](https://pytorch-lightning.readthedocs.io/en/latest/api/pytorch_lightning.trainer.trainer.html#pytorch_lightning.trainer.trainer.Trainer)\nclass. It's\n[**init**](https://pytorch-lightning.readthedocs.io/en/latest/api/pytorch_lightning.trainer.trainer.html#pytorch_lightning.trainer.trainer.Trainer.__init__)\nmethod provides various configuration options.\n\nIf you want to run K-Means with a GPU, you can pass the options `accelerator='gpu'` and `devices=1`\nto the estimator's initializer:\n\n```python\nestimator = KMeans(3, trainer_params=dict(accelerator='gpu', devices=1))\n```\n\nSimilarly, if you want to train on 4 nodes simultaneously where each node has one GPU available,\nyou can specify this as follows:\n\n```python\nestimator = KMeans(3, trainer_params=dict(num_nodes=4, accelerator='gpu', devices=1))\n```\n\nIn fact, **you do not need to change anything else in your code**.\n\n### Implemented Models\n\nCurrently, PyCave implements three different models:\n\n- [GaussianMixture](https://pycave.borchero.com/sites/generated/bayes/gmm/pycave.bayes.GaussianMixture.html)\n- [MarkovChain](https://pycave.borchero.com/sites/generated/bayes/markov_chain/pycave.bayes.MarkovChain.html)\n- [K-Means](https://pycave.borchero.com/sites/generated/clustering/kmeans/pycave.clustering.KMeans.html)\n\n## License\n\nPyCave is licensed under the [MIT License](https://github.com/borchero/pycave/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Traditional Machine Learning Models in PyTorch.",
"version": "3.2.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "a49559b2d8527f5806642cc5f292fab5",
"sha256": "48a2fd69bcd2ec04833f709c8fa9651d41c4be5a64835f0af5b8637f9932090a"
},
"downloads": -1,
"filename": "pycave-3.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a49559b2d8527f5806642cc5f292fab5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<3.11",
"size": 37218,
"upload_time": "2022-12-14T11:18:55",
"upload_time_iso_8601": "2022-12-14T11:18:55.338239Z",
"url": "https://files.pythonhosted.org/packages/d0/22/176d0dca19a4ad99e363f00a30402deea45b258b6042f8c09741f3566320/pycave-3.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "73f0bd3bcd1d73ab8309cce33c92bcf6",
"sha256": "2d4010289035ff047abaf423532ee87afb329e92d6f21b6b777daf468a458a54"
},
"downloads": -1,
"filename": "pycave-3.2.1.tar.gz",
"has_sig": false,
"md5_digest": "73f0bd3bcd1d73ab8309cce33c92bcf6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<3.11",
"size": 28828,
"upload_time": "2022-12-14T11:18:56",
"upload_time_iso_8601": "2022-12-14T11:18:56.688443Z",
"url": "https://files.pythonhosted.org/packages/b3/f8/b60008b98a741c3576d2ca990848085d59defe6bca9bc71373fdb864ad1f/pycave-3.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-14 11:18:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "borchero",
"github_project": "pycave",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycave"
}
JSON
