{"id":13497858,"url":"https://github.com/ermongroup/ncsn","last_synced_at":"2025-10-24T04:49:17.193Z","repository":{"id":46529321,"uuid":"196524942","full_name":"ermongroup/ncsn","owner":"ermongroup","description":"Noise Conditional Score Networks (NeurIPS 2019, Oral)","archived":false,"fork":false,"pushed_at":"2024-02-14T07:27:04.000Z","size":32810,"stargazers_count":725,"open_issues_count":9,"forks_count":107,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-24T17:05:55.589Z","etag":null,"topics":["generative-models","neurips-2019","score-based-generative-modeling","score-matching"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ermongroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-07-12T06:51:03.000Z","updated_at":"2025-05-21T13:01:20.000Z","dependencies_parsed_at":"2024-04-15T02:06:34.480Z","dependency_job_id":null,"html_url":"https://github.com/ermongroup/ncsn","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ermongroup/ncsn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermongroup%2Fncsn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermongroup%2Fncsn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermongroup%2Fncsn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermongroup%2Fncsn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ermongroup","download_url":"https://codeload.github.com/ermongroup/ncsn/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermongroup%2Fncsn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280742562,"owners_count":26382923,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-24T02:00:06.418Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["generative-models","neurips-2019","score-based-generative-modeling","score-matching"],"created_at":"2024-07-31T20:00:43.351Z","updated_at":"2025-10-24T04:49:17.179Z","avatar_url":"https://github.com/ermongroup.png","language":"Python","funding_links":[],"categories":["Papers"],"sub_categories":[],"readme":"# Generative Modeling by Estimating Gradients of the Data Distribution\n\nThis repo contains the official implementation for the NeurIPS 2019 paper \n[Generative Modeling by Estimating Gradients of the Data Distribution](https://arxiv.org/abs/1907.05600), \n\nby __Yang Song__ and __Stefano Ermon__. Stanford AI Lab.\n\n**Note**: **The method has been greatly stabilized by the subsequent work\n[Improved Techniques for Training Score-Based Generative Models](https://arxiv.org/abs/2006.09011) ([code](https://github.com/ermongroup/ncsnv2)) and more recently extended by [Score-Based Generative Modeling through Stochastic Differential Equations](https://arxiv.org/abs/2011.13456) ([code](https://github.com/yang-song/score_sde)). This codebase is therefore not recommended for new projects anymore.**\n\n-------------------------------------------------------------------------------------\nWe describe a new method of generative modeling based on estimating the derivative of the log density \nfunction (_a.k.a._, Stein score) of the data distribution. We first perturb our training data by different Gaussian noise with progressively smaller variances. Next, we estimate the score function for each perturbed data distribution, by training a shared neural network named the _Noise Conditional Score Network (NCSN)_ using _score matching_. We can directly produce samples from our NSCN with _annealed Langevin dynamics_.\n\n\n## Dependencies\n\n* PyTorch\n\n* PyYAML\n\n* tqdm\n\n* pillow\n\n* tensorboardX\n\n* seaborn\n\n\n## Running Experiments\n\n### Project Structure\n\n`main.py` is the common gateway to all experiments. Type `python main.py --help` to get its usage description.\n\n```bash\nusage: main.py [-h] [--runner RUNNER] [--config CONFIG] [--seed SEED]\n               [--run RUN] [--doc DOC] [--comment COMMENT] [--verbose VERBOSE]\n               [--test] [--resume_training] [-o IMAGE_FOLDER]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --runner RUNNER       The runner to execute\n  --config CONFIG       Path to the config file\n  --seed SEED           Random seed\n  --run RUN             Path for saving running related data.\n  --doc DOC             A string for documentation purpose\n  --verbose VERBOSE     Verbose level: info | debug | warning | critical\n  --test                Whether to test the model\n  --resume_training     Whether to resume training\n  -o IMAGE_FOLDER, --image_folder IMAGE_FOLDER\n                        The directory of image outputs\n```\n\nThere are four runner classes.\n\n* `AnnealRunner` The main runner class for experiments related to NCSN and annealed Langevin dynamics.\n* `BaselineRunner` Compared to `AnnealRunner`, this one does not anneal the noise. Instead, it uses a single fixed noise variance.\n* `ScoreNetRunner` This is the runner class for reproducing the experiment of Figure 1 (Middle, Right)\n* `ToyRunner` This is the runner class for reproducing the experiment of Figure 2 and Figure 3.\n\nConfiguration files are stored in  `configs/`. For example, the configuration file of `AnnealRunner` is `configs/anneal.yml`. Log files are commonly stored in `run/logs/doc_name`, and tensorboard files are in `run/tensorboard/doc_name`. Here `doc_name` is the value fed to option `--doc`.\n\n### Training\n\nThe usage of `main.py` is quite self-evident. For example, we can train an NCSN by running\n\n```bash\npython main.py --runner AnnealRunner --config anneal.yml --doc cifar10\n```\n\nThen the model will be trained according to the configuration files in `configs/anneal.yml`. The log files will be stored in `run/logs/cifar10`, and the tensorboard logs are in `run/tensorboard/cifar10`.\n\n### Sampling\n\nSuppose the log files are stored in `run/logs/cifar10`. We can produce samples to folder `samples` by running\n\n```bash\npython main.py --runner AnnealRunner --test -o samples\n```\n\n### Checkpoints\n\nWe provide pretrained checkpoints [run.zip](https://drive.google.com/file/d/1BF2mwFv5IRCGaQbEWTbLlAOWEkNzMe5O/view?usp=sharing). Extract the file to the root folder. You should be able to produce samples like the following using this checkpoint.\n\n| Dataset | Sampling procedure |\n| :------------ | :-------------------------: |\n| MNIST |  ![MNIST](assets/mnist_large.gif)|\n| CelebA |  ![Celeba](assets/celeba_large.gif)|\n|CIFAR-10 |  ![CIFAR10](assets/cifar10_large.gif)|\n\n### Evaluation\nPlease refer to Appendix B.2 of our paper for details on hyperparameters and model selection. When computing inception and FID scores, we first generate images from our model, and use the [official code from OpenAI](https://github.com/openai/improved-gan/tree/master/inception_score) and the [original code from TTUR authors](https://github.com/bioinf-jku/TTUR) to obtain the scores.\n\n\n## References\n\nLarge parts of the code are derived from [this Github repo](https://github.com/ermongroup/sliced_score_matching) (the official implementation of the [sliced score matching paper](https://arxiv.org/abs/1905.07088))\n\nIf you find the code / idea inspiring for your research, please consider citing the following\n\n```bib\n@inproceedings{song2019generative,\n  title={Generative Modeling by Estimating Gradients of the Data Distribution},\n  author={Song, Yang and Ermon, Stefano},\n  booktitle={Advances in Neural Information Processing Systems},\n  pages={11895--11907},\n  year={2019}\n}\n```\n\nand / or\n\n```bib\n@inproceedings{song2019sliced,\n  author    = {Yang Song and\n               Sahaj Garg and\n               Jiaxin Shi and\n               Stefano Ermon},\n  title     = {Sliced Score Matching: {A} Scalable Approach to Density and Score\n               Estimation},\n  booktitle = {Proceedings of the Thirty-Fifth Conference on Uncertainty in Artificial\n               Intelligence, {UAI} 2019, Tel Aviv, Israel, July 22-25, 2019},\n  pages     = {204},\n  year      = {2019},\n  url       = {http://auai.org/uai2019/proceedings/papers/204.pdf},\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fermongroup%2Fncsn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fermongroup%2Fncsn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fermongroup%2Fncsn/lists"}