# Metallurgy
[](https://metallurgy.readthedocs.io/en/latest/?badge=latest)
The Metallurgy package enables calculation of approximate properties of alloy
mixtures, based on the linear mixture of elemental properties.
## Installation
The metallurgy package can be installed from
[pypi](https://pypi.org/project/metallurgy/) using pip:
``pip install metallurgy``
## Usage
### Alloys
Most of the features of metallurgy are based on the concept of an alloy, a
mixture of elements:
```python
import metallurgy as mg
Bronze = mg.Alloy("Cu88Sn12")
```
An alloy can be defined in several ways:
```pycon
>>> mg.Alloy("Cu50Zr50")
Cu50Zr50
>>> mg.Alloy("CuZr")
Cu50Zr50
>>> mg.Alloy("CuZrFeCo")
Cu25Zr25Fe25Co25
>>> mg.Alloy("(Fe70Co30)50Ni50")
Ni50Fe35Co15
>>> mg.Alloy("(FeCo)50Ni50")
Ni50Fe25Co25
>>> mg.Alloy({"Pt": 30, "Al": 45, "Ag": 25})
Al45Pt30Ag25
```
While formally, an alloy is defined as ["a mixture of chemical elements of which
at least one is a metal"](https://en.wikipedia.org/wiki/Alloy), no such
limitation is enforced in this package -- you can create any mixture you want.
An Alloy object has access to properties containing the percentage values of the
composition, the elements in the composition, and has helper functions which can
convert the composition to a simple string or even a LaTeX formatted string:
```pycon
>>> Bronze.composition
{'Cu': 0.88, 'Sn': 0.12}
>>> Bronze.elements
['Cu', 'Sn']
>>> Bronze.to_string()
'Cu88Sn12'
>>> Bronze.to_pretty_string()
'Cu$_{88}$Sn$_{12}$'
```
### Calculating alloy properties
Properties of alloys may be approximated from the properties of their
constituent elements via the linear mixture rule:
$$\Sigma A = \sum_{i=1}^{N} c_i A_i $$
where $\Sigma A$ is the approximate mixed value of a property $A$ for an alloy
that contains $N$ elements with percentages $c_i$. Similarly, the deviation of
these elemental property values for the elements present in an alloy can be
calculated:
$$\delta A = \sqrt{\sum_{i=1}^{N} c_i \left(1 - \frac{A_i}{\Sigma A}\right)^2} $$
The metallurgy package can be used to calculate a variety of approximate alloy
properties:
```pycon
Bronze = mg.Alloy("Cu88Sn12")
>>> mg.linear_mixture(Bronze, "mass")
70.16568
>>> mg.linear_mixture(Bronze, "density")
8.7566
>>> mg.linear_mixture(Bronze, "valence")
2.24
>>> mg.deviation(Bronze, "mass")
17.926178182133523
>>> mg.deviation(Bronze, "density")
0.5508098038343185
>>> mg.deviation(Bronze, "valence")
0.6499230723708769
```
Elemental data is provided by the
[elementy](https://github.com/Robert-Forrest/elementy) package. Metallurgy can
calculate a variety of other alloy properties that are more complex than simple
linear mixture or deviations of elemental properties:
```pycon
>>> mg.enthalpy.mixing_Gibbs_free_energy(Bronze)
-2039.0961905675026
>>> mg.entropy.ideal_entropy(Bronze)
0.3669249912727096
>>> mg.density.theoretical_density(Bronze)
8.554783679490685
>>> mg.valence.d_valence(Bronze)
0.8661417322834646
```
See our June 2022 paper ["Machine-learning improves understanding of glass
formation in metallic
systems"](https://pubs.rsc.org/en/content/articlelanding/2022/dd/d2dd00026a)
that used code which later became the metallurgy package for definitions of
these alloy properties.
### Generating alloy datasets
Metallurgy can also be used to generate collections of alloys, either randomly
or across a composition-space.
```pycon
>>> mg.generate.binary(["Fe", "Co"], step=10)
[Fe100, Fe90Co10, Fe80Co20, Fe70Co30, Fe60Co40,
Fe50Co50, Co60Fe40, Co70Fe30, Co80Fe20, Co90Fe10, Co100]
>>> mg.generate.ternary(["Fe", "Co", "Al"], step=20)
[Fe100, Fe80Co20, Fe80Al20, Fe60Co40, Fe60Co20Al20,
Fe60Al40, Co60Fe40, Fe40Co40Al20, Fe40Al40Co20, Al60Fe40,
Co80Fe20, Co60Fe20Al20, Co40Al40Fe20, Al60Fe20Co20,
Al80Fe20, Co100, Co80Al20, Co60Al40, Al60Co40, Al80Co20, Al100]
>>> mg.generate.random_alloy()
Cs28.9Db25.4Hs12Ce11.9La10.6Cu9.6Kr1.6
>>> mg.generate.random_alloy()
Ba94.5Y5.5
```
We can apply constraints to the randomly generated alloy, such as limits on the
maximum and minimum number of constituent elements, requirements on the
percentage range that particular elements must be within, and whitelists of
allowed elements:
```pycon
>>> mg.generate.random_alloy(min_elements=2, max_elements=3)
Au50.7Hf36.3Ru13
>>> mg.generate.random_alloy(min_elements=2, max_elements=3, percentage_constraints={"Cu":{"min":0.3, "max":0.8}})
Cu63.9Sr23.9Be12.2
>>> mg.generate.random_alloy(min_elements=2, max_elements=3, percentage_constraints={"Cu":{"min":0.3, "max":0.8}}, allowed_elements=["Fe", "Cu", "Co", "Ni", "Yb"])
Yb64.8Cu30Ni5.2
```
The process of generating random alloys can be performed in bulk to create
datasets of random alloys:
```pycon
>>> mg.generate.random_alloys(10, min_elements=2, max_elements=3)
[Fl94.6Xe5.4, Po64.2Tl23.3Np12.5, Tb61.6Ta38.4, Lu50.8Ho38.1In11.1, Rn69Es31, S70.4Ts29.6, Pr79.3He13.4Cm7.3, As84.3V15.7, Ge45.3Xe41.2Na13.5, Ra70.4He29.6]
```
### Plotting alloy information
Once you have created a dataset of alloys, you may wish to view graphically a
particular material property on a population level:
```pycon
>>> binary, percentages = mg.generate.binary(["Cu", "Zr"])
>>> mixing_enthalpies = mg.enthalpy.mixing_enthalpy(binary)
>>> mg.plots.binary(binary, mixing_enthalpies, ylabel="Mixing enthalpy (kJ/mol)")
```
```pycon
>>> ternary, percentages = mg.generate.ternary(["Cu", "Zr", "Al"])
>>> mixing_enthalpies = mg.enthalpy.mixing_enthalpy(ternary)
>>> mg.plots.ternary(ternary, mixing_enthalpies, label="Mixing enthalpy (kJ/mol)")
```
```pycon
>>> import matplotlib.pyplot as plt
>>> alloys = mg.generate.random_alloys(10000)
>>> plt.hist(mg.linear_mixture(alloys, "density"))
```
## Documentation
Documentation is available [here.](https://metallurgy.readthedocs.io/en/latest/api.html)
Raw data
{
"_id": null,
"home_page": "https://github.com/Robert-Forrest/metallurgy",
"name": "metallurgy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Robert Forrest",
"author_email": "robertforrest@live.com",
"download_url": "https://files.pythonhosted.org/packages/41/1c/3ea9b100f797f5b33ad06e6a952a0564847c3f6215c11b5be097fa6e8e39/metallurgy-0.0.33.tar.gz",
"platform": "unix",
"description": "# Metallurgy\n\n\n[](https://metallurgy.readthedocs.io/en/latest/?badge=latest)\n\nThe Metallurgy package enables calculation of approximate properties of alloy\nmixtures, based on the linear mixture of elemental properties.\n\n\n## Installation\n\nThe metallurgy package can be installed from\n[pypi](https://pypi.org/project/metallurgy/) using pip:\n\n``pip install metallurgy``\n\n## Usage\n\n### Alloys\n\nMost of the features of metallurgy are based on the concept of an alloy, a\nmixture of elements:\n\n```python\nimport metallurgy as mg\n\nBronze = mg.Alloy(\"Cu88Sn12\")\n```\n\nAn alloy can be defined in several ways:\n\n```pycon\n>>> mg.Alloy(\"Cu50Zr50\")\nCu50Zr50\n\n>>> mg.Alloy(\"CuZr\")\nCu50Zr50\n\n>>> mg.Alloy(\"CuZrFeCo\")\nCu25Zr25Fe25Co25\n\n>>> mg.Alloy(\"(Fe70Co30)50Ni50\")\nNi50Fe35Co15\n\n>>> mg.Alloy(\"(FeCo)50Ni50\")\nNi50Fe25Co25\n\n>>> mg.Alloy({\"Pt\": 30, \"Al\": 45, \"Ag\": 25})\nAl45Pt30Ag25\n```\n\nWhile formally, an alloy is defined as [\"a mixture of chemical elements of which\nat least one is a metal\"](https://en.wikipedia.org/wiki/Alloy), no such\nlimitation is enforced in this package -- you can create any mixture you want.\n\nAn Alloy object has access to properties containing the percentage values of the\ncomposition, the elements in the composition, and has helper functions which can\nconvert the composition to a simple string or even a LaTeX formatted string:\n\n```pycon\n>>> Bronze.composition\n{'Cu': 0.88, 'Sn': 0.12}\n\n>>> Bronze.elements\n['Cu', 'Sn']\n\n>>> Bronze.to_string()\n'Cu88Sn12'\n\n>>> Bronze.to_pretty_string()\n'Cu$_{88}$Sn$_{12}$'\n```\n\n### Calculating alloy properties\n\nProperties of alloys may be approximated from the properties of their\nconstituent elements via the linear mixture rule:\n\n$$\\Sigma A = \\sum_{i=1}^{N} c_i A_i $$\n\nwhere $\\Sigma A$ is the approximate mixed value of a property $A$ for an alloy\nthat contains $N$ elements with percentages $c_i$. Similarly, the deviation of\nthese elemental property values for the elements present in an alloy can be\ncalculated:\n\n$$\\delta A = \\sqrt{\\sum_{i=1}^{N} c_i \\left(1 - \\frac{A_i}{\\Sigma A}\\right)^2} $$\n\nThe metallurgy package can be used to calculate a variety of approximate alloy\nproperties:\n\n```pycon\nBronze = mg.Alloy(\"Cu88Sn12\")\n\n>>> mg.linear_mixture(Bronze, \"mass\")\n70.16568\n\n>>> mg.linear_mixture(Bronze, \"density\")\n8.7566\n\n>>> mg.linear_mixture(Bronze, \"valence\")\n2.24\n\n>>> mg.deviation(Bronze, \"mass\")\n17.926178182133523\n\n>>> mg.deviation(Bronze, \"density\")\n0.5508098038343185\n\n>>> mg.deviation(Bronze, \"valence\")\n0.6499230723708769\n\n```\n\nElemental data is provided by the\n[elementy](https://github.com/Robert-Forrest/elementy) package. Metallurgy can\ncalculate a variety of other alloy properties that are more complex than simple\nlinear mixture or deviations of elemental properties:\n\n```pycon\n>>> mg.enthalpy.mixing_Gibbs_free_energy(Bronze)\n-2039.0961905675026\n\n>>> mg.entropy.ideal_entropy(Bronze)\n0.3669249912727096\n\n>>> mg.density.theoretical_density(Bronze)\n8.554783679490685\n\n>>> mg.valence.d_valence(Bronze)\n0.8661417322834646\n```\n\nSee our June 2022 paper [\"Machine-learning improves understanding of glass\nformation in metallic\nsystems\"](https://pubs.rsc.org/en/content/articlelanding/2022/dd/d2dd00026a)\nthat used code which later became the metallurgy package for definitions of\nthese alloy properties.\n\n### Generating alloy datasets\n\nMetallurgy can also be used to generate collections of alloys, either randomly\nor across a composition-space.\n\n```pycon\n>>> mg.generate.binary([\"Fe\", \"Co\"], step=10)\n[Fe100, Fe90Co10, Fe80Co20, Fe70Co30, Fe60Co40,\nFe50Co50, Co60Fe40, Co70Fe30, Co80Fe20, Co90Fe10, Co100]\n\n>>> mg.generate.ternary([\"Fe\", \"Co\", \"Al\"], step=20)\n[Fe100, Fe80Co20, Fe80Al20, Fe60Co40, Fe60Co20Al20,\nFe60Al40, Co60Fe40, Fe40Co40Al20, Fe40Al40Co20, Al60Fe40,\nCo80Fe20, Co60Fe20Al20, Co40Al40Fe20, Al60Fe20Co20,\nAl80Fe20, Co100, Co80Al20, Co60Al40, Al60Co40, Al80Co20, Al100]\n\n>>> mg.generate.random_alloy()\nCs28.9Db25.4Hs12Ce11.9La10.6Cu9.6Kr1.6\n\n>>> mg.generate.random_alloy()\nBa94.5Y5.5\n```\n\nWe can apply constraints to the randomly generated alloy, such as limits on the\nmaximum and minimum number of constituent elements, requirements on the\npercentage range that particular elements must be within, and whitelists of\nallowed elements:\n\n```pycon\n>>> mg.generate.random_alloy(min_elements=2, max_elements=3)\nAu50.7Hf36.3Ru13\n\n>>> mg.generate.random_alloy(min_elements=2, max_elements=3, percentage_constraints={\"Cu\":{\"min\":0.3, \"max\":0.8}})\nCu63.9Sr23.9Be12.2\n\n>>> mg.generate.random_alloy(min_elements=2, max_elements=3, percentage_constraints={\"Cu\":{\"min\":0.3, \"max\":0.8}}, allowed_elements=[\"Fe\", \"Cu\", \"Co\", \"Ni\", \"Yb\"])\nYb64.8Cu30Ni5.2\n```\n\nThe process of generating random alloys can be performed in bulk to create\ndatasets of random alloys:\n\n```pycon\n>>> mg.generate.random_alloys(10, min_elements=2, max_elements=3)\n[Fl94.6Xe5.4, Po64.2Tl23.3Np12.5, Tb61.6Ta38.4, Lu50.8Ho38.1In11.1, Rn69Es31, S70.4Ts29.6, Pr79.3He13.4Cm7.3, As84.3V15.7, Ge45.3Xe41.2Na13.5, Ra70.4He29.6]\n```\n\n### Plotting alloy information\n\nOnce you have created a dataset of alloys, you may wish to view graphically a\nparticular material property on a population level:\n\n```pycon\n>>> binary, percentages = mg.generate.binary([\"Cu\", \"Zr\"])\n>>> mixing_enthalpies = mg.enthalpy.mixing_enthalpy(binary)\n>>> mg.plots.binary(binary, mixing_enthalpies, ylabel=\"Mixing enthalpy (kJ/mol)\")\n```\n\n![CuZr binary mixing enthalpy](https://raw.githubusercontent.com/Robert-Forrest/metallurgy/main/images/CuZr_enthalpy.png \"Mixing enthalpy across the Cu-Zr composition\")\n\n```pycon\n>>> ternary, percentages = mg.generate.ternary([\"Cu\", \"Zr\", \"Al\"])\n>>> mixing_enthalpies = mg.enthalpy.mixing_enthalpy(ternary)\n>>> mg.plots.ternary(ternary, mixing_enthalpies, label=\"Mixing enthalpy (kJ/mol)\")\n```\n\n![CuZrAl ternary mixing enthalpy](https://raw.githubusercontent.com/Robert-Forrest/metallurgy/main/images/CuZrAl_enthalpy.png \"Mixing enthalpy across\nthe Cu-Zr-Al composition\")\n\n\n```pycon\n>>> import matplotlib.pyplot as plt\n>>> alloys = mg.generate.random_alloys(10000)\n>>> plt.hist(mg.linear_mixture(alloys, \"density\"))\n```\n\n![Histogram of densities](https://raw.githubusercontent.com/Robert-Forrest/metallurgy/main/images/AlloyDensities.png \"Histogram of the density of 10,000\nrandom alloys\")\n\n## Documentation\n\nDocumentation is available [here.](https://metallurgy.readthedocs.io/en/latest/api.html)\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Calculates approximate properties of alloy compositions.",
"version": "0.0.33",
"project_urls": {
"Homepage": "https://github.com/Robert-Forrest/metallurgy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c6ec7492fc69b81e580d6bce38c6ce516c273dea5c46d43b8dc845315a7398d2",
"md5": "a9e5f1712cc0263400d500c4a03fbd4e",
"sha256": "604a51413ba67a9754fb7795c8af285abe4c4819f60bccfe09bafdf9ab283296"
},
"downloads": -1,
"filename": "metallurgy-0.0.33-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a9e5f1712cc0263400d500c4a03fbd4e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 46218,
"upload_time": "2023-06-08T13:49:00",
"upload_time_iso_8601": "2023-06-08T13:49:00.511462Z",
"url": "https://files.pythonhosted.org/packages/c6/ec/7492fc69b81e580d6bce38c6ce516c273dea5c46d43b8dc845315a7398d2/metallurgy-0.0.33-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "411c3ea9b100f797f5b33ad06e6a952a0564847c3f6215c11b5be097fa6e8e39",
"md5": "e0d0abb287223332d9e1949ae0ce62ad",
"sha256": "597b4131e47f82edfd7e9ce259d6f93c4f13641b396d233b1f92404a2d41fa1a"
},
"downloads": -1,
"filename": "metallurgy-0.0.33.tar.gz",
"has_sig": false,
"md5_digest": "e0d0abb287223332d9e1949ae0ce62ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 217097,
"upload_time": "2023-06-08T13:49:02",
"upload_time_iso_8601": "2023-06-08T13:49:02.299835Z",
"url": "https://files.pythonhosted.org/packages/41/1c/3ea9b100f797f5b33ad06e6a952a0564847c3f6215c11b5be097fa6e8e39/metallurgy-0.0.33.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-08 13:49:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Robert-Forrest",
"github_project": "metallurgy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "metallurgy"
}
JSON
