| Name | xtal2txt JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Package to encode and decode crystal structures into text representations |
| upload_time | 2024-06-09 10:58:16 |
| maintainer | None |
| docs_url | None |
| author | Nawaf Alampara, Reza Aliakbari, Santiago Miret |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2024 lamalab-org Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
llm
materials
chemistry
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<img src="https://github.com/lamalab-org/xtal2txt/raw/main/docs/static/xtal2txt-logo.png" height="150">
</p>
<h1 align="center">
xtal2txt
</h1>
<p align="center">
<a href="https://github.com/lamalab-org/xtal2txt/actions/workflows/tests.yml">
<img alt="Tests" src="https://github.com/lamalab-org/xtal2txt/workflows/Tests/badge.svg" />
</a>
<a href="https://pypi.org/project/xtal2txt">
<img alt="PyPI" src="https://img.shields.io/pypi/v/xtal2txt" />
</a>
<a href="https://pypi.org/project/xtal2txt">
<img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/xtal2txt" />
</a>
</p>
Package to define, convert, encode and decode crystal structures into text representations.
`xtal2txt` is an important part of our [MatText](https://github.com/lamalab-org/MatText) framework.
## 💪 Getting Started
## 🚀 Installation
The most recent release can be installed from
[PyPI](https://pypi.org/project/xtal2txt/) with:
```shell
$ pip install xtal2txt
```
The most recent code and data can be installed directly from GitHub with:
```bash
$ pip install git+https://github.com/lamalab-org/xtal2txt.git
```
## Text Representation with xtal2txt
The `TextRep` class in `xtal2txt.core`
facilitates the transformation of crystal structures into different text
representations. Below is an example of its usage:
``` python
from xtal2txt.core import TextRep
from pymatgen.core import Structure
# Load structure from a CIF file
from_file = "InCuS2_p1.cif"
structure = Structure.from_file(from_file, "cif")
# Initialize TextRep Class
text_rep = TextRep.from_input(structure)
requested_reps = [
"cif_p1",
"slices",
"atom_sequences",
"atom_sequences_plusplus",
"crystal_text_llm",
"zmatrix"
]
# Get the requested text representations
requested_text_reps = text_rep.get_requested_text_reps(requested_reps)
```
## Using xtal2txt Tokenizers
By default, the tokenizer is initialized with `\[CLS\]` and `\[SEP\]`
tokens. For an example, see the `SliceTokenizer` usage:
``` python
from xtal2txt.tokenizer import SliceTokenizer
tokenizer = SliceTokenizer(
model_max_length=512,
truncation=True,
padding="max_length",
max_length=512
)
print(tokenizer.cls_token) # returns [CLS]
```
You can access the `\[CLS\]` token using the [cls_token]{.title-ref}
attribute of the tokenizer. During decoding, you can utilize the
[skip_special_tokens]{.title-ref} parameter to skip these special
tokens.
Decoding with skipping special tokens:
``` python
tokenizer.decode(token_ids, skip_special_tokens=True)
```
## Initializing tokenizers with custom special tokens
In scenarios where the `\[CLS\]` token is not required, you can initialize
the tokenizer with an empty special_tokens dictionary.
Initialization without `\[CLS\]` and `\[SEP\]` tokens:
``` python
tokenizer = SliceTokenizer(
model_max_length=512,
special_tokens={},
truncation=True,
padding="max_length",
max_length=512
)
```
All `Xtal2txtTokenizer` instances inherit from
[PreTrainedTokenizer](https://huggingface.co/docs/transformers/v4.40.1/en/main_classes/tokenizer#transformers.PreTrainedTokenizer) and accept arguments compatible with the Hugging Face tokenizer.
## Tokenizers with special number tokenization
The `special_num_token` argument (by default `False`) can be
set to true to tokenize numbers in a special way as designed and
implemented by
[RegressionTransformer](https://www.nature.com/articles/s42256-023-00639-z).
``` python
tokenizer = SliceTokenizer(
special_num_token=True,
model_max_length=512,
special_tokens={},
truncation=True,
padding="max_length",
max_length=512
)
```
## 👐 Contributing
Contributions, whether filing an issue, making a pull request, or forking, are appreciated. See
[CONTRIBUTING.md](https://github.com/lamalab-org/xtal2txt/blob/master/.github/CONTRIBUTING.md) for more information on getting involved.
## 👋 Attribution
### ⚖️ License
The code in this package is licensed under the MIT License.
See the [Notice](NOTICE.txt) for imported LGPL code.
### 💰 Funding
This project has been supported by the [Carl Zeiss Foundation](https://www.carl-zeiss-stiftung.de/en/) as well as Intel and Merck.
Raw data
{
"_id": null,
"home_page": null,
"name": "xtal2txt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Nawaf Alampara <nawaf.alampara@uni-jena.de>, Kevin Maik Jablonka <mail@kjablonka.com>",
"keywords": "llm, materials, chemistry",
"author": "Nawaf Alampara, Reza Aliakbari, Santiago Miret",
"author_email": "Kevin Maik Jablonka <mail@kjablonka.com>",
"download_url": "https://files.pythonhosted.org/packages/36/51/1ae508877fd0f8494dbf8cc3f0cfde9fe2b297d56c3b0626e036eb49d8f2/xtal2txt-0.1.0.tar.gz",
"platform": null,
"description": "\n<p align=\"center\">\n <img src=\"https://github.com/lamalab-org/xtal2txt/raw/main/docs/static/xtal2txt-logo.png\" height=\"150\">\n</p>\n\n\n<h1 align=\"center\">\n xtal2txt\n</h1>\n\n<p align=\"center\">\n <a href=\"https://github.com/lamalab-org/xtal2txt/actions/workflows/tests.yml\">\n <img alt=\"Tests\" src=\"https://github.com/lamalab-org/xtal2txt/workflows/Tests/badge.svg\" />\n </a>\n <a href=\"https://pypi.org/project/xtal2txt\">\n <img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/xtal2txt\" />\n </a>\n <a href=\"https://pypi.org/project/xtal2txt\">\n <img alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/xtal2txt\" />\n </a>\n</p>\n\nPackage to define, convert, encode and decode crystal structures into text representations.\n`xtal2txt` is an important part of our [MatText](https://github.com/lamalab-org/MatText) framework.\n\n## \ud83d\udcaa Getting Started\n\n## \ud83d\ude80 Installation\n\n\nThe most recent release can be installed from\n[PyPI](https://pypi.org/project/xtal2txt/) with:\n\n```shell\n$ pip install xtal2txt\n```\n\n\nThe most recent code and data can be installed directly from GitHub with:\n\n```bash\n$ pip install git+https://github.com/lamalab-org/xtal2txt.git\n```\n\n\n## Text Representation with xtal2txt\n\nThe `TextRep` class in `xtal2txt.core`\nfacilitates the transformation of crystal structures into different text\nrepresentations. Below is an example of its usage:\n\n``` python\nfrom xtal2txt.core import TextRep\nfrom pymatgen.core import Structure\n\n\n# Load structure from a CIF file\nfrom_file = \"InCuS2_p1.cif\"\nstructure = Structure.from_file(from_file, \"cif\")\n\n# Initialize TextRep Class\ntext_rep = TextRep.from_input(structure)\n\nrequested_reps = [\n \"cif_p1\",\n \"slices\",\n \"atom_sequences\",\n \"atom_sequences_plusplus\",\n \"crystal_text_llm\",\n \"zmatrix\"\n]\n\n# Get the requested text representations\nrequested_text_reps = text_rep.get_requested_text_reps(requested_reps)\n```\n\n\n## Using xtal2txt Tokenizers\n\nBy default, the tokenizer is initialized with `\\[CLS\\]` and `\\[SEP\\]`\ntokens. For an example, see the `SliceTokenizer` usage: \n\n``` python\nfrom xtal2txt.tokenizer import SliceTokenizer\n\ntokenizer = SliceTokenizer(\n model_max_length=512, \n truncation=True, \n padding=\"max_length\", \n max_length=512\n )\nprint(tokenizer.cls_token) # returns [CLS]\n```\n\nYou can access the `\\[CLS\\]` token using the [cls_token]{.title-ref}\nattribute of the tokenizer. During decoding, you can utilize the\n[skip_special_tokens]{.title-ref} parameter to skip these special\ntokens.\n\nDecoding with skipping special tokens:\n\n``` python\ntokenizer.decode(token_ids, skip_special_tokens=True)\n```\n\n\n## Initializing tokenizers with custom special tokens\n\nIn scenarios where the `\\[CLS\\]` token is not required, you can initialize\nthe tokenizer with an empty special_tokens dictionary.\n\nInitialization without `\\[CLS\\]` and `\\[SEP\\]` tokens:\n\n``` python\ntokenizer = SliceTokenizer(\n model_max_length=512, \n special_tokens={}, \n truncation=True,\n padding=\"max_length\", \n max_length=512\n )\n```\n\nAll `Xtal2txtTokenizer` instances inherit from\n[PreTrainedTokenizer](https://huggingface.co/docs/transformers/v4.40.1/en/main_classes/tokenizer#transformers.PreTrainedTokenizer) and accept arguments compatible with the Hugging Face tokenizer.\n\n## Tokenizers with special number tokenization\n\nThe `special_num_token` argument (by default `False`) can be\nset to true to tokenize numbers in a special way as designed and\nimplemented by\n[RegressionTransformer](https://www.nature.com/articles/s42256-023-00639-z).\n\n``` python\ntokenizer = SliceTokenizer(\n special_num_token=True,\n model_max_length=512, \n special_tokens={}, \n truncation=True,\n padding=\"max_length\", \n max_length=512\n )\n```\n\n## \ud83d\udc50 Contributing\n\nContributions, whether filing an issue, making a pull request, or forking, are appreciated. See\n[CONTRIBUTING.md](https://github.com/lamalab-org/xtal2txt/blob/master/.github/CONTRIBUTING.md) for more information on getting involved.\n\n## \ud83d\udc4b Attribution\n\n### \u2696\ufe0f License\n\nThe code in this package is licensed under the MIT License.\nSee the [Notice](NOTICE.txt) for imported LGPL code.\n\n### \ud83d\udcb0 Funding\n\nThis project has been supported by the [Carl Zeiss Foundation](https://www.carl-zeiss-stiftung.de/en/) as well as Intel and Merck.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 lamalab-org Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Package to encode and decode crystal structures into text representations",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/lamalab-org/xtal2txt",
"Issues": "https://github.com/lamalab-org/xtal2txt/issues"
},
"split_keywords": [
"llm",
" materials",
" chemistry"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a148c32f9425b91ab3d6942d2efe9b11f99b47c8b106f161def1b4de03c3adcc",
"md5": "b0bf4887891e00782ec116e8d784a7b0",
"sha256": "5b3ccaf569c829d2db4c7cd080910b9d282c467c93e2b2a37f242fa55ca366bd"
},
"downloads": -1,
"filename": "xtal2txt-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0bf4887891e00782ec116e8d784a7b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20536,
"upload_time": "2024-06-09T10:58:14",
"upload_time_iso_8601": "2024-06-09T10:58:14.990656Z",
"url": "https://files.pythonhosted.org/packages/a1/48/c32f9425b91ab3d6942d2efe9b11f99b47c8b106f161def1b4de03c3adcc/xtal2txt-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "36511ae508877fd0f8494dbf8cc3f0cfde9fe2b297d56c3b0626e036eb49d8f2",
"md5": "bcac68814ebc7c5c705966c54ea03308",
"sha256": "08c9d94235a096de5d1e83c66769188e1076da6df8838ca09889d4531ee816d9"
},
"downloads": -1,
"filename": "xtal2txt-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "bcac68814ebc7c5c705966c54ea03308",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 30701,
"upload_time": "2024-06-09T10:58:16",
"upload_time_iso_8601": "2024-06-09T10:58:16.888679Z",
"url": "https://files.pythonhosted.org/packages/36/51/1ae508877fd0f8494dbf8cc3f0cfde9fe2b297d56c3b0626e036eb49d8f2/xtal2txt-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-09 10:58:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lamalab-org",
"github_project": "xtal2txt",
"github_not_found": true,
"lcname": "xtal2txt"
}
