# cerebral
Tool for creating multi-output deep ensemble neural-networks for alloy property modelling.
See our paper [Machine-learning improves understanding of glass formation in
metallic
systems](https://pubs.rsc.org/en/content/articlelanding/2022/dd/d2dd00026a) for
discussion of the model, it's architecture, and performance.
## Installation
The cerebral package can be installed from
[pypi](https://pypi.org/project/cerebral/) using pip:
``pip install cerebral``
Cerebral makes heavy use of the
[metallurgy](https://github.com/Robert-Forrest/metallurgy) package to manipulate
and approximate properties of alloys. Cerebral can be used with the
[evomatic](https://github.com/Robert-Forrest/evomatic) package to perform alloy
searching.
## Usage
Cerebral can be used to create multi-input mult-output deep neural networks for
the modelling of arbitrary alloy properties.
The following example shows configuration of cerebral to predict the "price"
property of an alloy, based on atomic percentages alone. Cerebral is configured
to load data for this problem from the tests directory - this data is for
demonstration and testing only, it is synthetically created by the
[metallurgy](https://github.com/Robert-Forrest/metallurgy) package for the Cu-Zr
binary alloy system.
```python
import cerebral as cb
cb.setup(
{
"targets": [{"name": "price"}],
"input_features": [
"percentages"
],
"data": {"files": ["tests/CuZr_prices.csv"]},
}
)
data = cb.features.load_data()
```
```
>>> data
composition price Cu_percentage Zr_percentage
0 Cu100 6.000000 1.000 0.000
1 Cu99.9Zr0.1 6.044626 0.999 0.001
2 Cu99.7Zr0.3 6.133763 0.997 0.003
3 Cu99.6Zr0.4 6.178273 0.996 0.004
4 Cu99.4Zr0.6 6.267177 0.994 0.006
.. ... ... ... ...
662 Zr99.4Cu0.6 36.969779 0.006 0.994
663 Zr99.5Cu0.5 36.991515 0.005 0.995
664 Zr99.7Cu0.3 37.034949 0.003 0.997
665 Zr99.8Cu0.2 37.056646 0.002 0.998
666 Zr100 37.100000 0.000 1.000
```
Once a DataFrame of alloy compositions, input features, and prediction targets
is available, it can be used to train a model. The following example takes the
DataFrame created above, and trains a neural network to reproduce the target
features (for a maximum of 200 training epochs). The neural network model
produced is a standard Keras / TensorFlow model.
```python
model, history, train_data, test_data = cb.models.train_model(
data, max_epochs=200
)
>>> model
<keras.engine.functional.Functional object at 0x7f1810feac80>
>>> history.history["loss"]
[22.522766767894105, 21.966949822959215, ...]
```
Once a model has been created, cerebral provides automation for evaluating its
performance by comparison against the training and test datasets. Since the
pricing data is based on a very simple linear mixture, the model is able to
learn quite well the relationship between percentages of Cu and Zr and the
price.
```python
(
train_predictions,
train_errors,
test_predictions,
test_errors,
metrics,
) = cb.models.evaluate_model(
model,
train_data["dataset"],
train_data["labels"],
test_ds=test_data["dataset"],
test_labels=test_data["labels"],
train_compositions=train_data["compositions"],
test_compositions=test_data["compositions"],
)
>>> metrics
{
'price': {
'train': {
'R_sq': 0.9994298579318788,
'RMSE': 0.21407108083268242,
'MAE': 0.16591635524599488
},
'test': {
'R_sq': 0.9994089218056131,
'RMSE': 0.21349478924250365,
'MAE': 0.1721696906690461
}
}
}
```
Futher, the model can be used to generate predictions for arbitrary alloys, as
long as the required input features are supplied. Here, we see that the simple
example model predicts price value for pure copper which is in the vicinity of
the value originally calculated by linear mixture:
```python
>>> cb.models.predict(model, "Cu100")["price"]
{'price': array([6.60157898])}
>>> mg.calculate("Cu100", "price")
6.0
```
## Documentation
Documentation is available [here.](https://cerebral.readthedocs.io/en/latest/api.html)
Raw data
{
"_id": null,
"home_page": "https://github.com/Robert-Forrest/cerebral",
"name": "cerebral",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Robert Forrest",
"author_email": "robertforrest@live.com",
"download_url": "https://files.pythonhosted.org/packages/9c/6c/f2b783283d864b95d49c6aecb87fee4d698bd02493bbac430875eb21f2c5/cerebral-0.0.8.tar.gz",
"platform": "unix",
"description": "# cerebral\n\n\n\nTool for creating multi-output deep ensemble neural-networks for alloy property modelling.\n\nSee our paper [Machine-learning improves understanding of glass formation in\nmetallic\nsystems](https://pubs.rsc.org/en/content/articlelanding/2022/dd/d2dd00026a) for\ndiscussion of the model, it's architecture, and performance.\n\n## Installation\n\nThe cerebral package can be installed from\n[pypi](https://pypi.org/project/cerebral/) using pip:\n\n``pip install cerebral``\n\nCerebral makes heavy use of the\n[metallurgy](https://github.com/Robert-Forrest/metallurgy) package to manipulate\nand approximate properties of alloys. Cerebral can be used with the\n[evomatic](https://github.com/Robert-Forrest/evomatic) package to perform alloy\nsearching.\n\n## Usage\n\nCerebral can be used to create multi-input mult-output deep neural networks for\nthe modelling of arbitrary alloy properties.\n\nThe following example shows configuration of cerebral to predict the \"price\"\nproperty of an alloy, based on atomic percentages alone. Cerebral is configured\nto load data for this problem from the tests directory - this data is for\ndemonstration and testing only, it is synthetically created by the\n[metallurgy](https://github.com/Robert-Forrest/metallurgy) package for the Cu-Zr\nbinary alloy system.\n\n```python\nimport cerebral as cb\n\ncb.setup(\n {\n \"targets\": [{\"name\": \"price\"}],\n \"input_features\": [\n \"percentages\"\n ],\n \"data\": {\"files\": [\"tests/CuZr_prices.csv\"]},\n }\n)\n\ndata = cb.features.load_data()\n```\n\n```\n>>> data\n composition price Cu_percentage Zr_percentage\n0 Cu100 6.000000 1.000 0.000\n1 Cu99.9Zr0.1 6.044626 0.999 0.001\n2 Cu99.7Zr0.3 6.133763 0.997 0.003\n3 Cu99.6Zr0.4 6.178273 0.996 0.004\n4 Cu99.4Zr0.6 6.267177 0.994 0.006\n.. ... ... ... ...\n662 Zr99.4Cu0.6 36.969779 0.006 0.994\n663 Zr99.5Cu0.5 36.991515 0.005 0.995\n664 Zr99.7Cu0.3 37.034949 0.003 0.997\n665 Zr99.8Cu0.2 37.056646 0.002 0.998\n666 Zr100 37.100000 0.000 1.000\n```\n\nOnce a DataFrame of alloy compositions, input features, and prediction targets\nis available, it can be used to train a model. The following example takes the\nDataFrame created above, and trains a neural network to reproduce the target\nfeatures (for a maximum of 200 training epochs). The neural network model\nproduced is a standard Keras / TensorFlow model.\n\n```python\nmodel, history, train_data, test_data = cb.models.train_model(\n data, max_epochs=200\n)\n\n>>> model\n<keras.engine.functional.Functional object at 0x7f1810feac80>\n\n>>> history.history[\"loss\"]\n[22.522766767894105, 21.966949822959215, ...] \n\n```\n\nOnce a model has been created, cerebral provides automation for evaluating its\nperformance by comparison against the training and test datasets. Since the\npricing data is based on a very simple linear mixture, the model is able to\nlearn quite well the relationship between percentages of Cu and Zr and the\nprice.\n\n```python \n(\n train_predictions,\n train_errors,\n test_predictions,\n test_errors,\n metrics,\n) = cb.models.evaluate_model(\n model,\n train_data[\"dataset\"],\n train_data[\"labels\"],\n test_ds=test_data[\"dataset\"],\n test_labels=test_data[\"labels\"],\n train_compositions=train_data[\"compositions\"],\n test_compositions=test_data[\"compositions\"],\n)\n\n>>> metrics\n{\n 'price': {\n 'train': {\n 'R_sq': 0.9994298579318788, \n 'RMSE': 0.21407108083268242, \n 'MAE': 0.16591635524599488\n }, \n 'test': {\n 'R_sq': 0.9994089218056131,\n 'RMSE': 0.21349478924250365, \n 'MAE': 0.1721696906690461\n }\n }\n}\n\n```\n\nFuther, the model can be used to generate predictions for arbitrary alloys, as\nlong as the required input features are supplied. Here, we see that the simple\nexample model predicts price value for pure copper which is in the vicinity of\nthe value originally calculated by linear mixture: \n\n```python\n>>> cb.models.predict(model, \"Cu100\")[\"price\"]\n{'price': array([6.60157898])}\n\n>>> mg.calculate(\"Cu100\", \"price\")\n6.0\n```\n\n## Documentation\n\nDocumentation is available [here.](https://cerebral.readthedocs.io/en/latest/api.html)\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Tool for creating multi-output deep ensemble neural-networks",
"version": "0.0.8",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "0f9b2e07d8ea6b10d52b9d0399e9db98",
"sha256": "9cd9abc8f297ef0b190f8708627d47263ccd08440b59c595de9f9fba331f23b6"
},
"downloads": -1,
"filename": "cerebral-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f9b2e07d8ea6b10d52b9d0399e9db98",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 33618,
"upload_time": "2022-12-06T10:15:35",
"upload_time_iso_8601": "2022-12-06T10:15:35.674172Z",
"url": "https://files.pythonhosted.org/packages/f5/a5/5b9eb9d6ff94e88512e70a810e1c7a8e3a86ab9736caa57b5410eadba4af/cerebral-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "978c4bcf8164616eba9b0e1f5f72bc57",
"sha256": "1abfab334bd6332b20517312ea5211fe96545e4e93e48ba75a32ecce5d843c32"
},
"downloads": -1,
"filename": "cerebral-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "978c4bcf8164616eba9b0e1f5f72bc57",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 89033,
"upload_time": "2022-12-06T10:15:37",
"upload_time_iso_8601": "2022-12-06T10:15:37.564138Z",
"url": "https://files.pythonhosted.org/packages/9c/6c/f2b783283d864b95d49c6aecb87fee4d698bd02493bbac430875eb21f2c5/cerebral-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-06 10:15:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Robert-Forrest",
"github_project": "cerebral",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "cerebral"
}
JSON
