# mofstructure
This is an elaborate python module that provides simple functions for
manipulation metal-organic frameworks and other porous systems such as
COFs and Zeolites. Some uses of the module involves
1. Computation of geometric properties of MOFs. It calls zeo++ in the background and enables a quick computation of all porosity information such pld, lcd, asa ...
2. Automated removal of unbound guest molecules
3. Deconstruction of metal-organic frameworks into building units. And for each buidling units (organic ligand, metal cluster, organic sbu and metal sbu) computes their cheminformatic identifiers such as SMILES strings, inchi and inchikey. It also identify the type of metal sbu and coordination number of central metal.
4. Wraps systems around unit cell so as to remove effect of pbc. This is often the case, when one tries to visualize the cif files or convert cif files into xyz, the system often appears to be uncoordinated
5. Seperation of building units into regions. This is essential when on wishes to subsitute a specific ligand or building unit.
## Installation
### Option 1
```bash
pip install mofstructure
```
### Option 2
```bash
git clone https://github.com/bafgreat/mofstructure.git mofstructure
cd mofstructure
pip install .
```
## Quick start
### Run on the commandline
#### Building units
Simply run the following command on a cif file or any ase readable file format containing a MOF.
```bash
mofstructure cif_file
```
The script will deconstruct the MOF present in the cif file and load the output in a folder called 'MOF_building_units' in the current directory/folder. If you wish to load the output in a specific folder, simply add the path to the folder as follows:
```bash
mofstructure cif_file path_to_result_folder
```
For multiple cif files. Simply run a loop and all the Results will be saved in the
```bash
for cifs in ciffiles:
mofstructure cifs path_to_result
```
#### Creating a database
If you have a folder containg many cif files for different MOF, you could easily create a database. To create such a database, simply run the following command.
```bash
mofstructure_database ciffolder
```
Here the 'ciffolder' is the folder containing the cif files. The ouput will be saved in the default folder called 'MOFDb' in the current folder. Again you can choose the path to the save folder by simply listing it at the end of the command.
```bash
mofstructure_database ciffolder path_to_result
```
### Use as a libray
```Python
from mofstructure import mofdeconstructor
from mofstructure import porosity
from mofstructure import buildingunits
from ase.io import read, write
import pandas as pd
# Read cif file using ase
ase_atom = read(cif_file)
# check and remove unbound guest molecules
no_guest_indices = mofdeconstructor.remove_unbound_guest(ase_atom)
no_guest_atom = ase_atom[no_guest_indices]
# compute porosit and write output to csv
pores = porosity.zeo_calculation(ase_ato, probe_radius=1.86, number_of_steps=5000)
df = pd.DataFrame(pores, index=[0])
df.to_csv('pore.csv')
```
#### sbus and linkers
Compute sbus and linkers
```Python
connected_components, atoms_indices_at_breaking_point, porpyrin_checker, all_regions = MOF_deconstructor.secondary_building_units(ase_atom)
metal_sbus, organic_sbus, building_unit_regions = MOF_deconstructor.find_unique_building_units(
connected_components,
atoms_indices_at_breaking_point,
ase_atom,
porpyrin_checker,
all_regions,
cheminfo=True
)
```
#### when cheminfo = True
openbabel is called to compute all chemifomatic information,
which are all stored on the ase_atom.info
metal_sbus and organic_sbus list that contains all the unique instances of the metal sbus and organic sbus.
#### extracting cheminfor
For each instance in a building unit the various chemiformatic informations are as follows.
```Python
for i, sbu in enumerate(metal_sbu):
smi = sbu.info['smi']
inchi = sbu.info['inchi']
inchikey = sbu.info['inchikey]
# for sbus only
number_of_point_of_extension = sbu.info['point_of_extension']
#for metal sbus only
sbu_type = sbu.info['sbu_type'] # sbu_type :rodlike, irmof, uoi66, paddlewheel e.t.c
# write
sbu.write('metal_sbu_'+str(i)+'.cif')
```
## Summary
All of above codes can be run by a single function found mofstructure.buildingunits
### for a single cif file
```Python
from mofstructure import buildingunits
buildingunits.work_flow(ciffile, result_folder)
```
### for multiple cif files
```Python
from mofstructure import buildingunits
import glob
all_cifs = glob.glob(folder/*cif)
# folder corresponds to the folder containing all the cif files
for cif_files in all_cifs:
buildingunits.work_flow(cif_files, result_folder)
# Note that result_folder can be any path. If the path does not exist, it will create one and populate it with all the data.
```
## Documentation
You can access the full project documentation on [docs](https://bafgreat.github.io/mofstructure/)
## Roadmap
In the future the code should be able to:
1. Compute rcsr topological code
2. Subsitutue building units in a MOF to enable framework functionalisation
3. Automatic curation of cifs
4. Decontsruction of COFs into their building units
<!--  -->
<!-- ![proccess]source/(images/guest.png) -->
<!-- # Updates version 0.1.4
The new update enables the computation of open metal sites in cifs
To use this functionality run the following on the command line
```
mofstructure_database ciffolder --oms
```
Here ciffolder corresponse to the directory/folder containing the cif files.
After the computation the metal information will be found in a json file called `metal_info.json`. This file is found in the output folder that defaults to `MOFDb` incase none is provided.
# NB
Note that computing open metal sites is computationally expensive, especially if you intend to
run it on a folder with many cif files. There I recommend that if you are not interested in computing the open metal sites simply run command without the --oms option.
```
mofstructure_database ciffolder
```
This command will generate a MOFDb folder without the `metal_info.json` file. But the code will run very fast.
Also note that the `--oms` option is provided on for the `mofstructure_database` command. This is not available for `mofstructure` command which targets a single cif file. If you have a single cif file wish to compute open metal sites, simply put the cif file in a folder and rin `mofstructure_database` command on the folder (`mofstructure_database ciffolder --oms`).
# Updates version 0.1.5
The new update enables users to include a Rad file when computing porosity using pyzeo. This allows users to specify the type of radii to use. If omitted, the default pyzeo radii will be used, which are covalent radii obtained from the CSD.
Currently, this functionality can only be used when using mofstructure as a library. This can be done as follows:
```
from mofstructure.porosity import zeo_calculation
from ase.io import read
ase_atom = read(filename)
pore_data = zeo_calculation(ase_atom, rad_file='rad_file_name.rad')
```
# NB
Note that filename is any ASE-readable crystal structure file, ideally a CIF file. Moreover, rad_file_name.rad is a file containing the radii of each element present in the structure file. This should be formatted as follows:
```
element radii
```
For example, for an MgO system, your Rad file should look like this:
```
Mg 0.66
O 1.84
```
Also note that of the radii file does not have the .rad extension like `rad_file_name.rad` the default radii will be used.
# Updates version 0.1.6
Added new command line tools to expedite calculations especially when working on a quite large database.
## compute only deconstruction
If you wish to only compute the deconstruction of MOFs without having to compute
their porosity and open metal sites. Then simply run the following command
```
mofstructure_building_units cif_folder
```
## compute only porosity
If you wish to only compute the porosity using default values. i.e
probe radius = 1.86, number of gcmc cycles = 10000 and default csd atomic radii, then run the following command:
```
mofstructure_porosity cif_folder
```
However, if you wish to use another probe radius of maybe 1.5 and gcmc cycles of 20000 alongside custom atomic radii in a file called rad.rad, run the following command:
```
mofstructure_porosity cif_folder -pr 1.5 -ns 20000 -rf rad.rad
```
## compute only open metal sites
If you are only interested in computing the open metal sites, then running the following command
```
mofstructure_oms cif_folder
```
# Updates version 0.1.7
1. Implemented a robust CI/CD using git actions
2. Included add_dummy key to add dummy atoms to point of extension. This is important to effectively control the breaking point. This dummy atoms can then
be replaced with hydrogen to fully neutralize the system.
## N.B.
Be please don't use add dummy when deconstructing to ligands and clusters. The add dummy argument should be used only for sbus.
e.g
```
connected_components, atoms_indices_at_breaking_point, porpyrin_checker, all_regions = MOF_deconstructor.secondary_building_units(ase_atom)
metal_sbus, organic_sbus, building_unit_regions = MOF_deconstructor.find_unique_building_units(
connected_components,
atoms_indices_at_breaking_point,
ase_atom,
porpyrin_checker,
all_regions,
cheminfo=True,
add_dummy=True
)
metal_sbus[0].write('test1.xyz)
``` -->
Raw data
{
"_id": null,
"home_page": null,
"name": "mofstructure",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "guest removal, InChIKeys, InChI, SMILES, PLD, LCD, MOF, COF, zeolites, accessible surface area, void fraction, coordination number, porosity, zeo++, SBU, point of extension",
"author": "Dinga Wonanke",
"author_email": "bafgreat@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/94/29/bc6ed4961235dc93f0e4eafa10c39f23cbdf10f8dff80d4a016f65ce99bd/mofstructure-0.1.8.2.tar.gz",
"platform": null,
"description": "# mofstructure\n\n\n\nThis is an elaborate python module that provides simple functions for\nmanipulation metal-organic frameworks and other porous systems such as\nCOFs and Zeolites. Some uses of the module involves\n\n1. Computation of geometric properties of MOFs. It calls zeo++ in the background and enables a quick computation of all porosity information such pld, lcd, asa ...\n\n2. Automated removal of unbound guest molecules\n\n3. Deconstruction of metal-organic frameworks into building units. And for each buidling units (organic ligand, metal cluster, organic sbu and metal sbu) computes their cheminformatic identifiers such as SMILES strings, inchi and inchikey. It also identify the type of metal sbu and coordination number of central metal.\n\n4. Wraps systems around unit cell so as to remove effect of pbc. This is often the case, when one tries to visualize the cif files or convert cif files into xyz, the system often appears to be uncoordinated\n\n5. Seperation of building units into regions. This is essential when on wishes to subsitute a specific ligand or building unit.\n\n## Installation\n\n### Option 1\n\n```bash\npip install mofstructure\n```\n\n### Option 2\n\n```bash\n git clone https://github.com/bafgreat/mofstructure.git mofstructure\n cd mofstructure\n pip install .\n```\n\n## Quick start\n\n### Run on the commandline\n\n#### Building units\n\nSimply run the following command on a cif file or any ase readable file format containing a MOF.\n\n```bash\nmofstructure cif_file\n```\n\nThe script will deconstruct the MOF present in the cif file and load the output in a folder called 'MOF_building_units' in the current directory/folder. If you wish to load the output in a specific folder, simply add the path to the folder as follows:\n\n```bash\nmofstructure cif_file path_to_result_folder\n```\n\nFor multiple cif files. Simply run a loop and all the Results will be saved in the\n\n```bash\nfor cifs in ciffiles:\n mofstructure cifs path_to_result\n```\n\n#### Creating a database\n\nIf you have a folder containg many cif files for different MOF, you could easily create a database. To create such a database, simply run the following command.\n\n```bash\nmofstructure_database ciffolder\n```\n\nHere the 'ciffolder' is the folder containing the cif files. The ouput will be saved in the default folder called 'MOFDb' in the current folder. Again you can choose the path to the save folder by simply listing it at the end of the command.\n\n```bash\nmofstructure_database ciffolder path_to_result\n```\n\n### Use as a libray\n\n```Python\nfrom mofstructure import mofdeconstructor\nfrom mofstructure import porosity\nfrom mofstructure import buildingunits\nfrom ase.io import read, write\nimport pandas as pd\n\n# Read cif file using ase\nase_atom = read(cif_file)\n\n# check and remove unbound guest molecules\nno_guest_indices = mofdeconstructor.remove_unbound_guest(ase_atom)\nno_guest_atom = ase_atom[no_guest_indices]\n\n# compute porosit and write output to csv\npores = porosity.zeo_calculation(ase_ato, probe_radius=1.86, number_of_steps=5000)\ndf = pd.DataFrame(pores, index=[0])\ndf.to_csv('pore.csv')\n```\n\n#### sbus and linkers\n\nCompute sbus and linkers\n\n```Python\nconnected_components, atoms_indices_at_breaking_point, porpyrin_checker, all_regions = MOF_deconstructor.secondary_building_units(ase_atom)\n\nmetal_sbus, organic_sbus, building_unit_regions = MOF_deconstructor.find_unique_building_units(\n connected_components,\n atoms_indices_at_breaking_point,\n ase_atom,\n porpyrin_checker,\n all_regions,\n cheminfo=True\n )\n```\n\n#### when cheminfo = True\n\nopenbabel is called to compute all chemifomatic information,\nwhich are all stored on the ase_atom.info\nmetal_sbus and organic_sbus list that contains all the unique instances of the metal sbus and organic sbus.\n\n#### extracting cheminfor\n\nFor each instance in a building unit the various chemiformatic informations are as follows.\n\n```Python\nfor i, sbu in enumerate(metal_sbu):\n smi = sbu.info['smi']\n inchi = sbu.info['inchi']\n inchikey = sbu.info['inchikey]\n # for sbus only\n number_of_point_of_extension = sbu.info['point_of_extension']\n #for metal sbus only\n sbu_type = sbu.info['sbu_type'] # sbu_type :rodlike, irmof, uoi66, paddlewheel e.t.c\n # write\n sbu.write('metal_sbu_'+str(i)+'.cif')\n```\n\n## Summary\n\nAll of above codes can be run by a single function found mofstructure.buildingunits\n\n### for a single cif file\n\n```Python\nfrom mofstructure import buildingunits\nbuildingunits.work_flow(ciffile, result_folder)\n```\n\n### for multiple cif files\n\n```Python\nfrom mofstructure import buildingunits\nimport glob\nall_cifs = glob.glob(folder/*cif)\n# folder corresponds to the folder containing all the cif files\nfor cif_files in all_cifs:\n buildingunits.work_flow(cif_files, result_folder)\n# Note that result_folder can be any path. If the path does not exist, it will create one and populate it with all the data.\n```\n\n## Documentation\n\nYou can access the full project documentation on [docs](https://bafgreat.github.io/mofstructure/)\n\n## Roadmap\n\nIn the future the code should be able to:\n\n1. Compute rcsr topological code\n2. Subsitutue building units in a MOF to enable framework functionalisation\n3. Automatic curation of cifs\n4. Decontsruction of COFs into their building units\n <!--  -->\n\n<!-- ![proccess]source/(images/guest.png) -->\n\n<!-- # Updates version 0.1.4\n\nThe new update enables the computation of open metal sites in cifs\nTo use this functionality run the following on the command line\n\n```\nmofstructure_database ciffolder --oms\n```\n\nHere ciffolder corresponse to the directory/folder containing the cif files.\n\nAfter the computation the metal information will be found in a json file called `metal_info.json`. This file is found in the output folder that defaults to `MOFDb` incase none is provided.\n\n# NB\n\nNote that computing open metal sites is computationally expensive, especially if you intend to\nrun it on a folder with many cif files. There I recommend that if you are not interested in computing the open metal sites simply run command without the --oms option.\n\n```\nmofstructure_database ciffolder\n```\n\nThis command will generate a MOFDb folder without the `metal_info.json` file. But the code will run very fast.\n\nAlso note that the `--oms` option is provided on for the `mofstructure_database` command. This is not available for `mofstructure` command which targets a single cif file. If you have a single cif file wish to compute open metal sites, simply put the cif file in a folder and rin `mofstructure_database` command on the folder (`mofstructure_database ciffolder --oms`).\n\n# Updates version 0.1.5\n\nThe new update enables users to include a Rad file when computing porosity using pyzeo. This allows users to specify the type of radii to use. If omitted, the default pyzeo radii will be used, which are covalent radii obtained from the CSD.\n\nCurrently, this functionality can only be used when using mofstructure as a library. This can be done as follows:\n\n```\nfrom mofstructure.porosity import zeo_calculation\nfrom ase.io import read\n\nase_atom = read(filename)\n\npore_data = zeo_calculation(ase_atom, rad_file='rad_file_name.rad')\n```\n\n# NB\n\nNote that filename is any ASE-readable crystal structure file, ideally a CIF file. Moreover, rad_file_name.rad is a file containing the radii of each element present in the structure file. This should be formatted as follows:\n\n```\nelement radii\n```\n\nFor example, for an MgO system, your Rad file should look like this:\n\n```\nMg 0.66\nO 1.84\n```\n\nAlso note that of the radii file does not have the .rad extension like `rad_file_name.rad` the default radii will be used.\n\n# Updates version 0.1.6\n\nAdded new command line tools to expedite calculations especially when working on a quite large database.\n\n## compute only deconstruction\n\nIf you wish to only compute the deconstruction of MOFs without having to compute\ntheir porosity and open metal sites. Then simply run the following command\n\n```\nmofstructure_building_units cif_folder\n```\n\n## compute only porosity\n\nIf you wish to only compute the porosity using default values. i.e\nprobe radius = 1.86, number of gcmc cycles = 10000 and default csd atomic radii, then run the following command:\n\n```\nmofstructure_porosity cif_folder\n```\n\nHowever, if you wish to use another probe radius of maybe 1.5 and gcmc cycles of 20000 alongside custom atomic radii in a file called rad.rad, run the following command:\n\n```\nmofstructure_porosity cif_folder -pr 1.5 -ns 20000 -rf rad.rad\n```\n\n## compute only open metal sites\n\nIf you are only interested in computing the open metal sites, then running the following command\n\n```\nmofstructure_oms cif_folder\n```\n\n# Updates version 0.1.7\n\n1. Implemented a robust CI/CD using git actions\n2. Included add_dummy key to add dummy atoms to point of extension. This is important to effectively control the breaking point. This dummy atoms can then\n be replaced with hydrogen to fully neutralize the system.\n\n## N.B.\n\nBe please don't use add dummy when deconstructing to ligands and clusters. The add dummy argument should be used only for sbus.\ne.g\n\n```\nconnected_components, atoms_indices_at_breaking_point, porpyrin_checker, all_regions = MOF_deconstructor.secondary_building_units(ase_atom)\nmetal_sbus, organic_sbus, building_unit_regions = MOF_deconstructor.find_unique_building_units(\n connected_components,\n atoms_indices_at_breaking_point,\n ase_atom,\n porpyrin_checker,\n all_regions,\n cheminfo=True,\n add_dummy=True\n )\n\nmetal_sbus[0].write('test1.xyz)\n``` -->\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python tool to deconstruct MOFs into building units and compute porosity. The code removes guests from MOFs and all porous systems, computes SMILES strings and InChIKeys of all building units.",
"version": "0.1.8.2",
"project_urls": null,
"split_keywords": [
"guest removal",
" inchikeys",
" inchi",
" smiles",
" pld",
" lcd",
" mof",
" cof",
" zeolites",
" accessible surface area",
" void fraction",
" coordination number",
" porosity",
" zeo++",
" sbu",
" point of extension"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eadf2d30206e1d4de341eb6437b161dce42bf307ebf353268a45790a7a45b648",
"md5": "ac18681d6eec7a52aa562fe7f338fa4a",
"sha256": "ac7873821a82f34c0201f6bac13b6c3f09d7459520b2d781cd2eeee994d057b5"
},
"downloads": -1,
"filename": "mofstructure-0.1.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac18681d6eec7a52aa562fe7f338fa4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 40712,
"upload_time": "2024-11-13T11:57:59",
"upload_time_iso_8601": "2024-11-13T11:57:59.759057Z",
"url": "https://files.pythonhosted.org/packages/ea/df/2d30206e1d4de341eb6437b161dce42bf307ebf353268a45790a7a45b648/mofstructure-0.1.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9429bc6ed4961235dc93f0e4eafa10c39f23cbdf10f8dff80d4a016f65ce99bd",
"md5": "cb226f9222fc9b4e8ac2ca9902fed6eb",
"sha256": "477d90a172f33172886f33b4400bfa9e2c58b4a3bf4ebaf3b4b5dba052da15fa"
},
"downloads": -1,
"filename": "mofstructure-0.1.8.2.tar.gz",
"has_sig": false,
"md5_digest": "cb226f9222fc9b4e8ac2ca9902fed6eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 34244,
"upload_time": "2024-11-13T11:58:00",
"upload_time_iso_8601": "2024-11-13T11:58:00.991155Z",
"url": "https://files.pythonhosted.org/packages/94/29/bc6ed4961235dc93f0e4eafa10c39f23cbdf10f8dff80d4a016f65ce99bd/mofstructure-0.1.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 11:58:00",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mofstructure"
}
JSON