Package: ccsd
CCSD - Combinatorial Complex Score-based Diffusion Modelling through Stochastic Differential EquationsCCSDis a sophisticated score-based diffusion model designed to generate Combinatorial Complexes using Stochastic Differential Equations. This cutting-edge approach enables the generation of complex objects with higher-order structures and relations, thereby enhancing our ability to learn underlying distributions and produce more realistic objects.Table of ContentsCCSD - Combinatorial Complex Score-based Diffusion Modeling through Stochastic Differential EquationsTable of ContentsCCSDIntroductionWhy CCSD?AuthorContributionsInstallationUsing pipManuallyNext stepsPlotly engineDependencies and other packages/librariesTests and errorsDependenciesTestingDatasetsProcess molecular datasetsGenerate generic graphs datasetsUsageGeneralCommand lineCCSD classDocumentationCommons errorsInstallation of MOSESPackage-related errorsError due to MOSESError due to TopoNetX when running the testsCitationAcknowledgementChangelogLicenseCCSDIntroductionComplex object generation is a challenging problem with application in various fields such as drug discovery. The CCSD model offers a novel approach to tackle this problem by leveraging Diffusion Models and Stochastic Differential Equations to generate Combinatorial Complexes (CC). This topological structure generalizes the different mathematical stuctures used in Topological/Geometric Deep Learning to represent complex objects with higher-order structures and relations. The integration of the higher-order domain during the generation enhances the learning of the underlying distribution of the data and thus, allows for better data generation.If you find this project interesting, we would appreciate your support by leaving a star ⭐ on thisGitHub repository.Code still inAlpha version!Why CCSD?CCSD stands out from traditional complex object generation models due to the following key advantages:Combinatorial Complexes:The model generates Combinatorial Complexes, enabling the synthesis of complex objects with rich structures and relationships.Score-Based Diffusion:CCSD utilizes score-based diffusion techniques, allowing for efficient, high-quality and state-of-the-art complex object generation.Enhanced "Realism":By incorporating higher-order structures, the generated objects are more representative of the underlying data distribution.Also, thisrepository is highly documented and commented, which makes it easy to use, understand, deploy, and which offers endless possibilities for improvements.AuthorThe research has been conducted byAdrien Carrelas part of his requirements for the MSc degree in Advanced Computing of Imperial College London, United Kingdom, and his requirements for the MEng in Applied Mathematics (Diplôme d'Ingénieur) at CentraleSupélec, France.This project has beensupervised byDr. Tolga Birdal, Assistant Professor (Lecturer) in the Department of Computing of Imperial College London.ContributionsWe welcome new contributors with various background and programming levels who would like to contribute to the fields of diffusion models and topological deep learning. Feel free to suggest new ideas, submit pull requests, etc.Feel free to check ourCode of Conductif you wish to contribute.InstallationIf you encounter an error during the installation, please refer to the sectionCommons errorsbelow. If you are creating an Ubuntu instance on a Public Cloud service to train/sample from the model, you may want to use thepost_installation_script.shscript provided to automate the process (just modify theGit configurationssection inside the script with your details).Using pipTo get started with CCSD, you can install the package using pip by typing the command:pipinstallccsdManuallyIf you encounter, if you want to use the latest version, or if you prefer the command line interface, you can use it locally by cloning or forking this repository to your local machine.gitclonehttps://github.com/AdrienC21/CCSD.gitNext stepsPlotly engineFor Windows users, the recommended version of kaleido is0.1.0.post1. You can install it by typing:pipinstallkaleido==0.1.0post1For Linux users, the latest version of kaleido seems fine. For those who want to useorca, you can install it via thenpmcommand ofNode.js. For the installation, type:sudoNEEDRESTART_MODE=aaptinstall-ynodejs
sudoNEEDRESTART_MODE=aaptinstall-ynpm
npminstall-gelectron@6.1.4orcaDependencies and other packages/librariesInstall the dependencies (see the sectionDependenciesbelow).When installing PyTorch and its componenents, or when install TopoModelX along with TopoNetX, run the commands below:pipinstalltorch==2.0.1--extra-index-urlhttps://download.pytorch.org/whl/${CUDA}pipinstalltorch-scattertorch-sparse-fhttps://data.pyg.org/whl/torch-2.0.1+${CUDA}.htmlwhere ${CUDA} could becu117,cu118, orcpuif you want to use the CPU. For GPU, we recommendcu118. Also, TopoModelX should be installed after TopoNetX to avoid versioning issues.If you are using aLinuxsystem, you may need to install libxrender1 by typing:sudoapt-getinstalllibxrender1Tests and errorsTo test your installation, refer to the sectionTestingbelow.If you encounter an error, please refer to the sectionCommons errorsbelow.DependenciesCCSD requires a recent version of Python, probably 3.7, but preferably3.10 or higher.It also requires the following dependencies:dill>=0.3.6easydict>=1.10freezegun>=1.2.2hypernetx>=1.2.5imageio>=2.31.1joblib>=1.3.1kaleido>=0.1.0.post1matplotlib>=3.7.2networkx>=2.8.8numpy>=1.24.4pandas>=2.0.3plotly>=5.15.0pyemd>=1.0.0pytest>=7.4.0pytz>=2023.3pyyaml>=6.0rdkit>=2023.3.2scikit_learn>=1.3.0scipy>=1.11.1Cythonpomegranatetoponetxtorch>=2.0.1tqdm>=4.65.0molsets>=0.3.1pytest-covwandbpandas>=2.0.3Please make sure you have the required dependencies installed before using CCSD.You can install all of them by running the command:pipinstall-rrequirements.txtTestingTo ensure the correctness and robustness of CCSD and to allow researchers to build upon this tool, we have provided an extensive test suite. To run the tests, clone the repository, change your directory to the root folder of this project and execute the following command:pytesttests/-Wignore::DeprecationWarningIf you encounter an error during the testing, please refer to the sectionCommons errorsbelow.The output should look like this:====================================================testsessionstarts====================================================...

tests\utils\test_mol_utils.py..................[98%]tests\utils\test_time_utils.py..[100%]==============================================128passedin70.03s(0:01:10)===============================================DatasetsFor more information about the script below and their arguments, you can type:python<script_path>--helpProcess molecular datasetsIf you want to use molecular datasets such as QM9 or ZINC250k, you first need to run the two following commands:pythonccsd/data/preprocess.py--dataset<dataset_name>--folder<folder_name>
pythonccsd/data/preprocess_for_nspdk.py--dataset<dataset_name>--folder<folder_name><dataset_name>has to be chosen from this list:["QM9", "ZINC250k"].<folder_name>is the location of thedatafolder that contains the datasets (default to./).Generate generic graphs datasetsIf you want to generate generic graphs datasets, you can run the following command:pythonccsd/data/data_generators.py--dataset<dataset_name>--folder<folder_name><dataset_name>has to be chosen from this list:["community_small", "grid", "ego_small", "ENZYMES"].<folder_name>is the location of thedatafolder that will contain the generated dataset (default to./).UsageFor a more complete documentation on all the classes and functions, please refer to theDocumentationpage (link in the section below) andhere.GeneralTo use CCSD, follow the steps outlined below:Edit your general configurations:Edit the fileconfig\general_config.pyto provide yourwandb(Weights & Biases) information (if you want to use wandb), your timezone, and some other general parameters.Edit theenginevalue with the plotly engine you want to use. For Windows users, we recommendkaleido(see installation instructions below). For Linux users, we recommendorca(see installation instructions below).Execute the code:You can either use the command line or directly the CCSD class (more information in the subsections below).Combinatorial Complexes:To generate combinatorial complexes and not graphs, just put the parameteris_ccto True in your configuration files, specify thed_minandd_maxparameters of your dataset (see the thesis for more information on that), and pick a ScoreNetwork model for the rank2 score predictions (see example of configurations).Figures and output:The figures, the graphs, combinatorial complexes, molecules, etc, will all be saved into asamplesfolder, and in the logs folderslogs_sampleandlogs_train.The output in the command line should look like below, where a logo is printed, the current experiment information, and then the training/sampling information:PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP5JJJJJJJJJJJJJJJJJJJJJJJJJJJJJJJJYPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP?7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPP5YY5PPPPPPPPPP5YY5PPPPPPPPPPPPPPPPPP?.^!7?????7!^.7PPPPPPPPPPPPPP
PPPPPPPPPPPPPP5^.~JYYY55557^....^?PPPPPPPPPPPPPPPP?:!J5PPPPPPPPPPP5J!.7PPPPPPPPPPPPPP
PPPPPPPPPPPPPP?:^~^~PPPPPPPPPPPPPPP?.?5PPPPPPPPPPPPPPPPP5!7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPP?^:^?J??777?...:5PPPPPPPPPPPPPP?^5PPPPPP5?~^^~!?5PPPY!:7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPG5^:^.^::75PPPPPPPPPPPP?:5PPPPPP7..7!:7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPP5!.!?^^~JJ~.^!^^^~75PPPPP?7PPPPPPJ7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPY!.~YPPPPPPPPY^.?PPPP?JPPPPPP!7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPP5557.~YPPPPPPPPPPJ:PPPP?!PPPPPPJ7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPJ~....:~YPPPPPPPPPPPP5:7PPPP?.YPPPPPP?.:?7^.7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPJ:5PPPPPPPPPPPPP57^...:~JPPPPP?.JPPPPPP5?!~~~!?5PPP5J!.7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPJ.5PPPPPPPPPPPPPPPP555PPPPPPPP?!5PPPPPPPPPPPPPPPPP577PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPJ^...:~YPPPPPPPPPPPPPPPPPPPPPPPPPPPP?.~?5PPPPPPPPPPP5J~.7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPP5555PPPPPPPPPPPPPPPPPPPPPPPPPPPPPP?.:~!7??77!~:.7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP?7PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP5YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY5PPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP____________________PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP/____/____|/____|__\PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP|||||(___||||PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP||||\___\||||PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP||___||________)||__||PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP\_____\_____|_____/|_____/PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
PPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPPP
----------------------------------------------------------------------------------------------------
Currentexperiment:type:trainconfig:qm9comment:seed:42...Command lineHelp:Get more information by typing:pythonmain.py--helpTrain a model:Define your own config or use one from theconfigfolder.Use the command:pythonmain.py--typetrain--config<config_name>where<config_name>should be the name of your configuration file.If you want to sample directly after the training of your model, just provide in the configuration file the sampling parameters.Sample from a model:Define your own sample config or use one from theconfigfolder.Use the command:pythonmain.py--typesample--config<config_name>where<config_name>should be the name of your sampling configuration file.Other:Other parameters include:--comment COMMENT: A single line comment for the experiment--seed SEED: Random seed for reproducibility--folder FOLDER: Directory to save the results, load checkpoints, load config, etcTo provide additional information about the GPU, you can provide the ID(s) of the GPU(s) to use by typing:CUDA_VISIBLE_DEVICES=0,1pythonmain.py--type<type>--config<config_name>if you want to use the GPUs 0 and 1, or to only use the GPU 0:CUDA_VISIBLE_DEVICES=0pythonmain.py--type<type>--config<config_name>CCSD classRun an experiment by adapting the code below:fromccsd.diffusionimportCCSDparams={"type":"train","config":"qm9_CC","folder":"./",# optional"comment":"test experiment",# optional"seed":42# optional}diffusion_model=CCSD(**params)# define the objectdiffusion_model.run()# run the experimentTo get more information about the parameters and the other functions availables, you can ask for help by typing:fromccsdimportCCSDhelp(CCSD)DocumentationHere is the link to the documentation of this library:https://ccsd.readthedocs.io/en/latest/. It contains more information regarding all the classes and functions of this package.Commons errorsInstallation of MOSESIf you encounter an error during the installation of MOSES, please follow the steps below:First, if you are on Windows, make sure you have installed theC++ Dev kit via Visual Studio 2022 community.Then, for all users, install rdkit, Cython, and pomegranate using the commands:pipinstallrdkit
pipinstallCython
pipinstallpomegranateFinally, either install MOSES directly using:pipinstallmolsetsOr, first install lfs by runningcurl-shttps://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh|sudobash
sudoapt-getinstallgit-lfs
git-lfsinstallAnd then use one of the two options below to install MOSES:1 - via gitgitlfsinstall
pipinstallgit+https://github.com/molecularsets/moses.git2 - install it manually (if the previous steps doesn't work):gitlfsinstall
gitclonehttps://github.com/molecularsets/moses.gitcdmoses
pythonsetup.pyinstallPackage-related errorsThe errors related to packages (MOSES, TopoNetX, etc) can be fixed by running the scriptapply_fixes.pylocated in.github/workflows/or by following the steps for each individual packages below:Error due to MOSESIf you get an error related to a._appendmethod that no longer exists in Pandas and that is still used in the MOSES package, please replace in the MOSES package the fileutils.pywith the one provided in this repository:fixes\utils.py. The MOSESutils.pyfile should be located somewhere like:C:\Users\<username>\miniconda3\lib\site-packages\moses\metrics\utils.pyorminiconda\lib\python3.11\site-packages\molsets-1.0-py3.11.egg\moses\metrics\utils.pyMore precisely the error should look like this:_mcf.append(_pains,sort=True)['smarts'].values]...
AttributeError:'DataFrame'objecthasnoattribute'append'The trick is to replace this line (24) by:pd.concat([_mcf,_pains],sort=True)['smarts'].values]Remark:The entire operation can be done through the command line by using sed:sed-i"24s/.*/\t\t\tpd.concat([_mcf, _pains], sort=True)[\o047smarts\o047].values]/"<path_to_moses_utils.py>Error due to TopoNetX when running the testsInstall an old version ofTopoNetX, by running for example the command:pipinstallgit+https://github.com/pyt-team/TopoNetX.git@a389bd8bb11c731bb98d79da8392e3396ea9db8cThen, replace the filecombinatorial_complex.pyof TopoNetX by the updated one provided in this repository:fixes\combinatorial_complex.pyThe file in TopoNetX should be located somewhere like:C:\Users\<username>\miniconda3\Lib\site-packages\toponetx\classes\combinatorial_complex.pyorminiconda\lib\python3.11\site-packages\toponetx\classes\combinatorial_complex.pyCitationIf you use CCSD in your research or work, please consider citing it using the following BibTeX entry:Carrel, A. (2023). CCSD - Combinatorial Complex Score-based Diffusion model using stochastic differential equations. (Version 1.0.0) [Computer software]. https://github.com/AdrienC21/CCSDAcknowledgementThe Laboratory for Computational Physiology (LCP) at the Massachusetts Institute of Technology (MIT) for partially hosting me during the redaction of my thesis.Dr. Tolga Birdalfor his supervision and for the valuable advice and ressources that he provided.Dr. Mustafa Hajijand the members of thepyt-teamfor the packageTopoNetXand their work on Combinatorial Complexes and Topological Deep Learning:Topological Deep Learning: Going Beyond Graph Data.Jo, J. & al.for their paperScore-based Generative Modeling of Graphs via the System of Stochastic Differential Equationsthat served as a baseline for both the theoretical and empirical part of this work.All my friends and my family for the support.Logo created by me using the icon: "topology" icon by VectorsLab from Noun Project CC BY 3.0.ChangelogSee thechange logfor a history of all changes toCCSD.LicenseCCSD is licensed under theMIT License. Feel free to use and modify the code as per the terms of the license.Changelog0.3.3 (2023/09/18)Debug like 0.3.1 (add path to general_config in diffusion.py and main.py)0.3.2 (2023/09/18)Debug like 0.3.10.3.1 (2023/09/18)Debug folder structure when calling some functionsAdd example script and notebook0.3.0 (2023/09/18)Debugging, additional plotsMore configuration options with more datasetsNew scripts (Tanimoto similarity, plot datasets)0.2.1 (2023/08/13)Debug the initial release of the package.0.2.0 (2023/08/13)Debug the initial release of the package.0.1.0 (2023/08/10)Version 1 of the CCSD Python package.