diff --git a/docs/source/basic_examples.rst b/docs/source/basic_examples.rst index 3e492e73a..923846881 100644 --- a/docs/source/basic_examples.rst +++ b/docs/source/basic_examples.rst @@ -1130,6 +1130,109 @@ from the database. For example, pymongo.MongoClient().drop_database(_test_database) pymongo.MongoClient = _mongo_client +Visualising Molecular Datasets using chemiscope +=============================================== + + +Requirements +------------ + +:mod:`chemiscope` makes it easy for you to write a ``.json`` or ``.json.gz`` +containing :mod:`stk` molecules and their properties; see an example__. + +__ https://chemiscope.org/docs/examples/9-showing_custom_bonds.html + +To get :mod:`.chemiscope`, you can install it with pip:: + + $ pip install chemiscope + +Writing to file +--------------- + +:mod:`chemiscope` can be used through the `web-interface`__ or can be embedded +into read-the-docs pages through a sphinx package, like for `toy models`__. + +__ https://chemiscope.org/ + +__ https://cgmodels.readthedocs.io/en/latest/cg_model_jul2023_2p3_ton.html + +Either way, you need to write a ``.json`` or ``.json.gz`` file + +.. testcode:: saving-to-chemiscope + + import stk + import chemiscope + + structures = [ + stk.BuildingBlock(smiles="NCCN"), + stk.BuildingBlock(smiles="NCCCN"), + # A mostly optimised cage molecule. + stk.ConstructedMolecule( + topology_graph=stk.cage.FourPlusSix( + building_blocks=( + stk.BuildingBlock( + smiles="NCCN", + functional_groups=[stk.PrimaryAminoFactory()], + ), + stk.BuildingBlock( + smiles="O=CC(C=O)C=O", + functional_groups=[stk.AldehydeFactory()], + ), + ), + optimizer=stk.MCHammer(), + ), + ) + ] + + # Write their properties to a dictionary. + properties = { + "num_atoms": [molecule.get_num_atoms() for molecule in structures], + "num_bonds": [ + len(list(molecule.get_bonds())) for molecule in structures + ], + } + + # Define stk bonding. + shape_dict = chemiscope.convert_stk_bonds_as_shapes( + frames=structures, + bond_color="#fc5500", + bond_radius=0.12, + ) + + # Write the shape string for settings to turn them on automatically. + shape_string = ",".join(shape_dict.keys()) + + # Write to file. + chemiscope.write_input( + path="stk_example.json.gz", + frames=structures, + properties=properties, + meta=dict(name="A name."), + settings=chemiscope.quick_settings( + x="num_atoms", + y="num_bonds", + color="", + structure_settings={ + "shape": shape_string, + "atoms": True, + "bonds": False, + "spaceFilling": False, + }, + ), + shapes=shape_dict, + ) + +.. testcleanup:: saving-to-chemiscope + + import pathlib + + pathlib.Path("stk_example.json.gz").unlink() + +.. seealso:: + + chemiscope: https://chemiscope.org/ + + Specifying Functional Groups Individually ========================================= diff --git a/pyproject.toml b/pyproject.toml index 39ab56a8d..26e1909ea 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -43,6 +43,7 @@ dev = [ "sphinx-copybutton", "sphinx-rtd-theme", "twine", + "chemiscope", ] [project.urls]