{"id":23580745,"url":"https://github.com/davidnabergoj/nfmc","last_synced_at":"2025-11-02T12:30:26.856Z","repository":{"id":269447232,"uuid":"664351170","full_name":"davidnabergoj/nfmc","owner":"davidnabergoj","description":"This package implements various flow-based MCMC algorithms for statistical analyses and sampling.","archived":false,"fork":false,"pushed_at":"2025-01-19T22:42:27.000Z","size":2158,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-19T23:35:24.875Z","etag":null,"topics":["bayesian-inference","markov-chain-monte-carlo","normalizing-flows","pytorch","sampling","simulation","statistical-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidnabergoj.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,"publiccode":null,"codemeta":null}},"created_at":"2023-07-09T17:54:49.000Z","updated_at":"2025-01-12T12:55:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"fbb4acbf-aa37-42e4-9ece-0b35d8515679","html_url":"https://github.com/davidnabergoj/nfmc","commit_stats":{"total_commits":280,"total_committers":1,"mean_commits":280.0,"dds":0.0,"last_synced_commit":"30c282ee5440ac6177d58e54d3e7ee1356a77454"},"previous_names":["davidnabergoj/nfmc"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidnabergoj%2Fnfmc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidnabergoj%2Fnfmc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidnabergoj%2Fnfmc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidnabergoj%2Fnfmc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidnabergoj","download_url":"https://codeload.github.com/davidnabergoj/nfmc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239394715,"owners_count":19631122,"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","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":["bayesian-inference","markov-chain-monte-carlo","normalizing-flows","pytorch","sampling","simulation","statistical-analysis"],"created_at":"2024-12-27T00:12:38.098Z","updated_at":"2025-11-02T12:30:26.827Z","avatar_url":"https://github.com/davidnabergoj.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Markov Chain Monte Carlo with Normalizing Flows\n\nThis package provides various sampling algorithms that utilize normalizing flows (NF):\n\n* Independent Metropolis Hastings (IMH)\n* Metropolis adjusted Langevin algorithm (MALA)\n* Unadjusted Langevin algorithm (MALA)\n* NeuTra HMC\n* Transport elliptical slice sampling (TESS)\n* Deterministic Langevin Monte Carlo (DLMC)\n\nThe following algorithms are yet to be added:\n\n* Preconditioned Monte Carlo (PMC)\n* Flow annealed importance sampling bootstrap (FAB)\n* Nested sampling (NS)\n* Stochastic normalizing flows (SNF)\n* Annealed flow transport Monte Carlo (AFT)\n* Continual repeated annealed flow transport Monte Carlo (CRAFT)\n\nWe term such NF-based MCMC algorithms as NFMC.\n\n## Usage instructions\n\nNFMC algorithms require a target potential and an NF object.\nThe potential is a function that computes the negative unnormalized log probability density of the target distribution.\nExample potentials are provided in the accompanying [potentials package](https://github.com/davidnabergoj/potentials).\nThis package depends on [torchflows](https://github.com/davidnabergoj/torchflows) for NF definitions.\nPlease implement custom NF architectures in torchflows for compatibility with this package.\n\nAn example using Real NVP and a standard Gaussian potential is shown below.\n\n```python\nimport torch\nfrom nfmc import sample\n\ntorch.manual_seed(0)  # Set the random seed for reproducible results\n\nn_iterations = 1000\nn_chains = 100\nn_dim = 25  # Each draw (event) is a vector with size 25.\n\n\n# Define the target potential\ndef standard_gaussian_potential(x):\n    return torch.sum(x ** 2, dim=-1)\n\n\n# Draw samples with Jump MALA (also local-global MALA)\nmala_out = sample(\n    standard_gaussian_potential,\n    event_shape=(n_dim,),\n    strategy=\"jump_mala\",\n    flow=\"realnvp\",\n    n_chains=n_chains,\n    n_iterations=n_iterations\n)\n```\n\nTo use different samplers, pass the following keyword arguments to the `sample` function:\n\n```python\nfrom nfmc import sample\n\nsample(..., strategy='jump_mh')         # Metropolis-Hastings with NF jumps\nsample(..., strategy='imh')             # Independent Metropolis-Hastings\nsample(..., strategy='adaptive_imh')    # Adaptive independent Metropolis-Hastings\nsample(..., strategy='jump_mala')       # Metropolis adjusted Langevin algorithm with NF jumps\nsample(..., strategy='jump_ula')        # Unadjusted Langevin algorithm with NF jumps\nsample(..., strategy='jump_hmc')        # Hamiltonian Monte Carlo with NF jumps\nsample(..., strategy='jump_uhmc')       # Unadjusted Hamiltonian Monte Carlo with NF jumps\nsample(..., strategy='jump_ess')        # Elliptical slice sampling with NF jumps\nsample(..., strategy='jump_ess')        # Elliptical slice sampling with NF jumps\nsample(..., strategy='tess')            # Transport elliptical slice sampling\nsample(..., strategy='dlmc')            # Deterministic Langevin Monte Carlo\nsample(..., strategy='neutra_hmc')      # NeuTra HMC\nsample(..., strategy='neutra_mh')       # NeuTra MH\n```\n\nThe output of the `sample` method is an `MCMCOutput` object with useful properties for model analyses and sampler debugging:\n\n```python\nout = sample(...)\n\nout.samples         # tensor of samples\nout.mean            # mean tensor\nout.variance        # variance tensor\nout.second_moment   # second moment tensor\nout.statistics      # MCMCStatistics object with convergence monitoring logs and other MCMC-related quantities (e.g., acceptance rate, number of target calls, number of target gradient calls)  \n``` \n\nOther samplers may be used by explicitly creating the sampler object and calling the `sample` method.\nWe provide an example for Jump HMC and the standard Gaussian potential:\n\n```python\nimport torch\nfrom nfmc.algorithms.sampling.nfmc.jump import JumpHMC\n\ntorch.manual_seed(0)\nevent_shape = (10,)\n\n\ndef standard_gaussian_potential(x):\n    return torch.sum(x ** 2, dim=-1)\n\n\nsampler = JumpHMC(event_shape, standard_gaussian_potential)\n\nn_chains = 100\nx_initial = torch.randn(size=(n_chains, *event_shape)) / 10\nout = sampler.sample(x_initial)\n```\n\nYou can check the list of supported NFs with:\n\n```python\nfrom nfmc.util import get_supported_normalizing_flows\n\nprint(get_supported_normalizing_flows())\n```\n\n## Installation\n\nThis package was tested with Python version 3.10, however we expect Python versions 3.7+ to also work.\nThis package depends on [torchflows](https://github.com/davidnabergoj/torchflows).\n\nInstall the package directly from Github:\n```\npip install git+https://github.com/davidnabergoj/nfmc.git\n```\n\nTo alternatively configure the package for local development, clone the repository and install dependencies:\n\n```\ngit clone git@github.com:davidnabergoj/nfmc.git\npip install torchflows\n```\n## Contributing\n\nWe warmly welcome any contributions or comments.\nSome aspects of the package that can be improved:\n\n* Additional sampler tests.\n* Implementation of PMC, NS, SNF, AFT, CRAFT, FAB and other NFMC methods.\n* Configuring a continuous integration pipeline with Github actions.\n* Suggestions for improved default sampler hyperparameters.\n\n## Citation\n\nIf you use this code in your work, we kindly ask that you cite the accompanying paper:\n\u003e [Nabergoj and Štrumbelj: Empirical evaluation of normalizing flows in Markov Chain Monte Carlo, 2024. arxiv:2412.17136.](https://arxiv.org/abs/2412.17136)\n\nBibTex entry:\n```\n@misc{nabergoj_nf_mcmc_evaluation_2024,\n    author = {Nabergoj, David and \\v{S}trumbelj, Erik},\n    title = {Empirical evaluation of normalizing flows in {Markov} {Chain} {Monte} {Carlo}},\n    publisher = {arXiv},\n    month = dec,\n    year = {2024},\n    note = {arxiv:2412.17136}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidnabergoj%2Fnfmc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidnabergoj%2Fnfmc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidnabergoj%2Fnfmc/lists"}