rbms 0.1__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. {rbms-0.1 → rbms-0.2.0}/.github/workflows/codecov.yaml +4 -9
  2. {rbms-0.1 → rbms-0.2.0}/.github/workflows/test.yaml +4 -9
  3. rbms-0.2.0/.github/workflows/whats_new.yaml +18 -0
  4. {rbms-0.1 → rbms-0.2.0}/PKG-INFO +52 -23
  5. rbms-0.2.0/README.md +95 -0
  6. rbms-0.2.0/docs/source/auto_examples/images/sphx_glr_plot_generated_samples_001.png +0 -0
  7. rbms-0.2.0/docs/source/auto_examples/images/sphx_glr_plot_generated_samples_002.png +0 -0
  8. rbms-0.2.0/docs/source/auto_examples/images/sphx_glr_plot_generated_samples_003.png +0 -0
  9. rbms-0.2.0/docs/source/auto_examples/images/sphx_glr_plot_generated_samples_004.png +0 -0
  10. rbms-0.2.0/docs/source/auto_examples/images/thumb/sphx_glr_plot_generated_samples_thumb.png +0 -0
  11. {rbms-0.1 → rbms-0.2.0}/docs/source/auto_examples/plot_generated_samples.codeobj.json +14 -0
  12. {rbms-0.1 → rbms-0.2.0}/docs/source/auto_examples/plot_generated_samples.ipynb +1 -1
  13. rbms-0.2.0/docs/source/auto_examples/plot_generated_samples.py.md5 +1 -0
  14. {rbms-0.1 → rbms-0.2.0}/docs/source/auto_examples/plot_generated_samples.rst +4 -4
  15. {rbms-0.1 → rbms-0.2.0}/docs/source/auto_examples/sg_execution_times.rst +2 -2
  16. {rbms-0.1 → rbms-0.2.0}/docs/source/index.md +10 -14
  17. {rbms-0.1 → rbms-0.2.0}/docs/source/sg_execution_times.rst +2 -2
  18. {rbms-0.1 → rbms-0.2.0}/docs/source/tuto/dataset.md +2 -3
  19. rbms-0.2.0/docs/source/tuto/train_rbm.md +51 -0
  20. {rbms-0.1/docs/source/auto_examples → rbms-0.2.0/examples}/plot_generated_samples.py +2 -2
  21. {rbms-0.1 → rbms-0.2.0}/pyproject.toml +1 -3
  22. {rbms-0.1 → rbms-0.2.0}/rbms/bernoulli_bernoulli/classes.py +1 -1
  23. {rbms-0.1 → rbms-0.2.0}/rbms/classes.py +83 -47
  24. {rbms-0.1 → rbms-0.2.0}/rbms/dataset/__init__.py +1 -1
  25. {rbms-0.1 → rbms-0.2.0}/rbms/dataset/fasta_utils.py +3 -3
  26. {rbms-0.1 → rbms-0.2.0}/rbms/dataset/load_fasta.py +8 -9
  27. {rbms-0.1 → rbms-0.2.0}/rbms/io.py +17 -10
  28. {rbms-0.1 → rbms-0.2.0}/rbms/map_model.py +2 -2
  29. {rbms-0.1 → rbms-0.2.0}/rbms/metrics/aats.py +1 -2
  30. {rbms-0.1 → rbms-0.2.0}/rbms/parser.py +23 -2
  31. {rbms-0.1 → rbms-0.2.0}/rbms/partition_function/ais.py +12 -11
  32. {rbms-0.1 → rbms-0.2.0}/rbms/partition_function/exact.py +17 -3
  33. {rbms-0.1 → rbms-0.2.0}/rbms/plot.py +6 -44
  34. {rbms-0.1 → rbms-0.2.0}/rbms/potts_bernoulli/classes.py +6 -2
  35. {rbms-0.1 → rbms-0.2.0}/rbms/potts_bernoulli/implement.py +33 -20
  36. {rbms-0.1 → rbms-0.2.0}/rbms/potts_bernoulli/utils.py +4 -1
  37. {rbms-0.1 → rbms-0.2.0}/rbms/sampling/gibbs.py +3 -6
  38. {rbms-0.1 → rbms-0.2.0}/rbms/sampling/pt.py +16 -20
  39. rbms-0.2.0/rbms/scripts/__init__.py +0 -0
  40. {rbms-0.1 → rbms-0.2.0}/rbms/scripts/entrypoint.py +2 -2
  41. {rbms-0.1 → rbms-0.2.0}/rbms/scripts/pt_sampling.py +11 -11
  42. {rbms-0.1 → rbms-0.2.0}/rbms/scripts/train_rbm.py +4 -7
  43. {rbms-0.1 → rbms-0.2.0}/rbms/training/pcd.py +15 -12
  44. {rbms-0.1 → rbms-0.2.0}/rbms/training/utils.py +12 -10
  45. {rbms-0.1 → rbms-0.2.0}/rbms/utils.py +6 -2
  46. {rbms-0.1 → rbms-0.2.0}/tests/conftest.py +1 -0
  47. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/test_methods_bbrbm.py +3 -0
  48. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/test_methods_pbrbm.py +3 -0
  49. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/training/test_pcd.py +19 -2
  50. {rbms-0.1 → rbms-0.2.0}/tests/use_cases/test_bbrbm.py +3 -2
  51. {rbms-0.1 → rbms-0.2.0}/tests/use_cases/test_pbrbm.py +7 -3
  52. rbms-0.1/README.md +0 -65
  53. rbms-0.1/docs/source/Makefile +0 -20
  54. rbms-0.1/docs/source/auto_examples/images/sphx_glr_plot_generated_samples_001.png +0 -0
  55. rbms-0.1/docs/source/auto_examples/images/sphx_glr_plot_generated_samples_002.png +0 -0
  56. rbms-0.1/docs/source/auto_examples/images/sphx_glr_plot_generated_samples_003.png +0 -0
  57. rbms-0.1/docs/source/auto_examples/images/sphx_glr_plot_generated_samples_004.png +0 -0
  58. rbms-0.1/docs/source/auto_examples/images/sphx_glr_plot_test_001.png +0 -0
  59. rbms-0.1/docs/source/auto_examples/images/thumb/sphx_glr_plot_generated_samples_thumb.png +0 -0
  60. rbms-0.1/docs/source/auto_examples/images/thumb/sphx_glr_plot_test_thumb.png +0 -0
  61. rbms-0.1/docs/source/auto_examples/plot_generated_samples.py.md5 +0 -1
  62. rbms-0.1/docs/source/auto_examples/plot_test.codeobj.json +0 -18
  63. rbms-0.1/docs/source/auto_examples/plot_test.ipynb +0 -43
  64. rbms-0.1/docs/source/auto_examples/plot_test.py +0 -10
  65. rbms-0.1/docs/source/auto_examples/plot_test.py.md5 +0 -1
  66. rbms-0.1/docs/source/auto_examples/plot_test.rst +0 -85
  67. rbms-0.1/docs/source/tuto/train_rbm.md +0 -38
  68. {rbms-0.1 → rbms-0.2.0}/.github/workflows/docs.yaml +0 -0
  69. {rbms-0.1 → rbms-0.2.0}/.gitignore +0 -0
  70. {rbms-0.1 → rbms-0.2.0}/LICENSE +0 -0
  71. {rbms-0.1 → rbms-0.2.0}/MANIFEST.in +0 -0
  72. {rbms-0.1 → rbms-0.2.0}/docs/Makefile +0 -0
  73. {rbms-0.1 → rbms-0.2.0}/docs/make.bat +0 -0
  74. {rbms-0.1 → rbms-0.2.0}/docs/source/api.md +0 -0
  75. {rbms-0.1 → rbms-0.2.0}/docs/source/auto_examples/index.rst +0 -0
  76. {rbms-0.1/examples → rbms-0.2.0/docs/source/auto_examples}/plot_generated_samples.py +0 -0
  77. {rbms-0.1 → rbms-0.2.0}/docs/source/conf.py +0 -0
  78. {rbms-0.1 → rbms-0.2.0}/docs/source/examples.md +0 -0
  79. {rbms-0.1 → rbms-0.2.0}/docs/source/myst.yml +0 -0
  80. {rbms-0.1 → rbms-0.2.0}/docs/source/rbm.md +0 -0
  81. {rbms-0.1 → rbms-0.2.0}/docs/source/references.bib +0 -0
  82. {rbms-0.1 → rbms-0.2.0}/docs/source/tuto/parallel_tempering.md +0 -0
  83. {rbms-0.1 → rbms-0.2.0}/docs/source/tutorials.md +0 -0
  84. /rbms-0.1/rbms/__init__.py → /rbms-0.2.0/docs/source/whats_new.rst +0 -0
  85. {rbms-0.1 → rbms-0.2.0}/examples/GALLERY_HEADER.rst +0 -0
  86. {rbms-0.1/rbms/metrics → rbms-0.2.0/rbms}/__init__.py +0 -0
  87. {rbms-0.1 → rbms-0.2.0}/rbms/bernoulli_bernoulli/__init__.py +0 -0
  88. {rbms-0.1 → rbms-0.2.0}/rbms/bernoulli_bernoulli/functional.py +0 -0
  89. {rbms-0.1 → rbms-0.2.0}/rbms/bernoulli_bernoulli/implement.py +0 -0
  90. {rbms-0.1 → rbms-0.2.0}/rbms/const.py +0 -0
  91. {rbms-0.1 → rbms-0.2.0}/rbms/custom_fn.py +0 -0
  92. {rbms-0.1 → rbms-0.2.0}/rbms/dataset/dataset_class.py +0 -0
  93. {rbms-0.1 → rbms-0.2.0}/rbms/dataset/load_h5.py +0 -0
  94. {rbms-0.1 → rbms-0.2.0}/rbms/dataset/parser.py +0 -0
  95. {rbms-0.1 → rbms-0.2.0}/rbms/dataset/utils.py +0 -0
  96. {rbms-0.1/rbms/potts_bernoulli → rbms-0.2.0/rbms/metrics}/__init__.py +0 -0
  97. {rbms-0.1/rbms/scripts → rbms-0.2.0/rbms/potts_bernoulli}/__init__.py +0 -0
  98. {rbms-0.1 → rbms-0.2.0}/rbms/potts_bernoulli/functional.py +0 -0
  99. {rbms-0.1 → rbms-0.2.0}/rbms/potts_bernoulli/tools.py +0 -0
  100. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/implement/test_compute_energy_bbrbm.py +0 -0
  101. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/implement/test_compute_energy_hiddens_bbrbm.py +0 -0
  102. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/implement/test_compute_energy_visibles_bbrbm.py +0 -0
  103. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/implement/test_compute_gradient_bbrbm.py +0 -0
  104. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/implement/test_init_chains_bbrbm.py +0 -0
  105. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/implement/test_init_parameters_bbrbm.py +0 -0
  106. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/implement/test_sample_hiddens_bbrbm.py +0 -0
  107. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/implement/test_sample_visibles_bbrbm.py +0 -0
  108. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/test_bernoulli_utils_bbrbm.py +0 -0
  109. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/bernoulli_bernoulli/test_functional_bbrbm.py +0 -0
  110. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/metrics/test_aats.py +0 -0
  111. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/implement/test_compute_energy_hiddens_pbrbm.py +0 -0
  112. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/implement/test_compute_energy_pbrbm.py +0 -0
  113. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/implement/test_compute_energy_visibles_pbrbm.py +0 -0
  114. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/implement/test_compute_gradient_pbrbm.py +0 -0
  115. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/implement/test_init_chains_pbrbm.py +0 -0
  116. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/implement/test_init_parameters_pbrbm.py +0 -0
  117. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/implement/test_sample_hiddens_pbrbm.py +0 -0
  118. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/implement/test_sample_visibles_pbrbm.py +0 -0
  119. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/test_functional_pbrbm.py +0 -0
  120. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/potts_bernoulli/test_utils_pbrbm.py +0 -0
  121. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/test_custom_fn.py +0 -0
  122. {rbms-0.1 → rbms-0.2.0}/tests/unit_test/test_utils.py +0 -0
@@ -1,11 +1,9 @@
1
1
  name: Run tests and upload coverage
2
2
 
3
- on:
4
- push
3
+ on: [push, pull_request, workflow_dispatch]
5
4
 
6
5
  jobs:
7
6
  test:
8
- if: github.ref == 'refs/heads/main'
9
7
  name: Run tests on latest python version and collect coverage
10
8
  runs-on: ubuntu-latest
11
9
  steps:
@@ -26,16 +24,13 @@ jobs:
26
24
  run: pip install -e .
27
25
 
28
26
  - name: Get data for binary use case
29
- run:
30
- wget https://github.com/nbereux/data_test/raw/refs/heads/main/dummy.zip
27
+ run: wget https://github.com/nbereux/data_test/raw/refs/heads/main/dummy.zip
31
28
 
32
29
  - name: Get data for potts use case
33
- run:
34
- wget https://github.com/nbereux/data_test/raw/refs/heads/main/dummy.fasta
30
+ run: wget https://github.com/nbereux/data_test/raw/refs/heads/main/dummy.fasta
35
31
 
36
32
  - name: Extract binary data
37
- run:
38
- unzip ./dummy.zip
33
+ run: unzip ./dummy.zip
39
34
 
40
35
  - name: Run tests
41
36
  run: PYTORCH_JIT=0 pytest --cov=rbms tests/
@@ -1,11 +1,9 @@
1
1
  name: Run tests and upload coverage
2
2
 
3
- on:
4
- push
3
+ on: [push, pull_request, workflow_dispatch]
5
4
 
6
5
  jobs:
7
6
  test:
8
- if: github.ref == 'refs/heads/main'
9
7
  name: Run tests on previous python versions
10
8
  runs-on: ubuntu-latest
11
9
  strategy:
@@ -29,16 +27,13 @@ jobs:
29
27
  run: pip install .
30
28
 
31
29
  - name: Get data for binary use case
32
- run:
33
- wget https://github.com/nbereux/data_test/raw/refs/heads/main/dummy.zip
30
+ run: wget https://github.com/nbereux/data_test/raw/refs/heads/main/dummy.zip
34
31
 
35
32
  - name: Get data for potts use case
36
- run:
37
- wget https://github.com/nbereux/data_test/raw/refs/heads/main/dummy.fasta
33
+ run: wget https://github.com/nbereux/data_test/raw/refs/heads/main/dummy.fasta
38
34
 
39
35
  - name: Extract binary data
40
- run:
41
- unzip dummy.zip
36
+ run: unzip dummy.zip
42
37
 
43
38
  - name: Run tests
44
39
  run: pytest tests/
@@ -0,0 +1,18 @@
1
+ name: Check What's News Changes
2
+
3
+ concurrency:
4
+ group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
5
+ cancel-in-progress: true
6
+
7
+ on:
8
+ pull_request:
9
+ types: [assigned, opened, synchronize, reopened, labeled, unlabeled]
10
+ branches:
11
+ - "*"
12
+ jobs:
13
+ check-whats-news:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: tarides/changelog-check-action@v2
17
+ with:
18
+ changelog: docs/source/whats_new.rst
@@ -1,12 +1,13 @@
1
- Metadata-Version: 2.3
1
+ Metadata-Version: 2.4
2
2
  Name: rbms
3
- Version: 0.1
3
+ Version: 0.2.0
4
4
  Summary: Training and analyzing Restricted Boltzmann Machines in PyTorch
5
5
  Project-URL: Homepage, https://github.com/DsysDML/rbms
6
6
  Project-URL: Issues, https://github.com/DsysDML/rbms/issues
7
7
  Author: Aurélien Decelle, Cyril Furtlehner, Alfonso Navas, Lorenzo Rosset, Beatriz Seoane
8
8
  Author-email: Nicolas Béreux <nicolas.bereux@gmail.com>
9
9
  Maintainer-email: Nicolas Béreux <nicolas.bereux@gmail.com>
10
+ License-File: LICENSE
10
11
  Keywords: Restricted Boltzmann Machine,rbm
11
12
  Classifier: License :: OSI Approved :: MIT License
12
13
  Classifier: Operating System :: OS Independent
@@ -15,8 +16,6 @@ Requires-Python: >=3.11
15
16
  Requires-Dist: h5py>=3.12.0
16
17
  Requires-Dist: matplotlib>=3.8.0
17
18
  Requires-Dist: numpy<=2.1.2,>=2.0.0
18
- Requires-Dist: scikit-learn==1.5.2
19
- Requires-Dist: seaborn>=0.13.0
20
19
  Requires-Dist: torch<=2.5.0,>=2.0.0
21
20
  Requires-Dist: tqdm>=4.65.0
22
21
  Description-Content-Type: text/markdown
@@ -25,7 +24,6 @@ Description-Content-Type: text/markdown
25
24
  [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
26
25
  ![Static Badge](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-green)
27
26
 
28
-
29
27
  # RBMs
30
28
 
31
29
  ## Overview
@@ -33,18 +31,43 @@ Description-Content-Type: text/markdown
33
31
  `rbms` is a GPU-accelerated package designed to train and analyze Restricted Boltzmann Machines (RBMs). It is intended for students and researchers who need an efficient tool for working with RBMs.
34
32
  Features:
35
33
 
36
- - GPU Acceleration through PyTorch.
37
- - Multiple RBM Types: Supports Bernoulli-Bernoulli RBM and Potts-Bernoulli RBM.
38
- - Extensible Design: Provides an abstract class RBM with methods that can be implemented for new types of RBMs, minimizing the need to reimplement training algorithms, analysis methods, and sampling methods.
34
+ - GPU Acceleration through PyTorch.
35
+ - Multiple RBM Types: Supports Bernoulli-Bernoulli RBM and Potts-Bernoulli RBM.
36
+ - Extensible Design: Provides an abstract class RBM with methods that can be implemented for new types of RBMs, minimizing the need to reimplement training algorithms, analysis methods, and sampling methods.
39
37
 
40
38
  ## Installation
41
39
 
42
- To install TorchRBM, you can use pip:
40
+ ### PyPI
41
+
42
+ `rbms` can be installed from PyPI:
43
+
44
+ ```bash
45
+ pip install rbms
46
+ ```
47
+
48
+ The last version on PyPI corresponds to the main branch of this repo. To update the installed package run
43
49
 
44
50
  ```bash
45
- pip install .
51
+ pip install rbms --upgrade
46
52
  ```
47
53
 
54
+ ### Github
55
+
56
+ If you want a more up-to-date version or wish to contribute, you can install the package directly from this repository:
57
+
58
+ ```bash
59
+ git clone git@github.com:DsysDML/rbms.git
60
+ cd rbms && pip install -e .
61
+ ```
62
+
63
+ If you want to update the package run
64
+
65
+ ```bash
66
+ git pull
67
+ ```
68
+
69
+ from inside the cloned repo.
70
+
48
71
  ## Dependencies
49
72
 
50
73
  The dependencies are included in the pyproject.toml file and should be compiled in the wheel distribution. If you have a GPU, make sure to install PyTorch with GPU support.
@@ -52,17 +75,22 @@ The dependencies are included in the pyproject.toml file and should be compiled
52
75
  ## Usage
53
76
 
54
77
  Main Classes and Functions:
55
- - `RBM`: An abstract class that provides the basic structure and methods for RBMs.
56
- - `BBRBM`: A concrete implementation of the Bernoulli-Bernoulli RBM.
57
- - `PBRBM`: A concrete implementation of the Potts-Bernoulli RBM.
58
- - `rbms.sampling`: Submodule for sampling methods.
59
- - `rbms.training`: Submodule for training algorithms.
78
+
79
+ - `EBM`: An abstract class that provides the basic structure and methods for Energy-Based Models (EBMs).
80
+ - `RBM`: An abstract class that provides the basic structure and methods for RBMs.
81
+ - `BBRBM`: A concrete implementation of the Bernoulli-Bernoulli RBM.
82
+ - `PBRBM`: A concrete implementation of the Potts-Bernoulli RBM.
83
+ - `rbms.sampling`: Submodule for sampling methods.
84
+ - `rbms.training`: Submodule for training algorithms.
60
85
 
61
86
  ## Basic Example
62
87
 
63
88
  Train a RBM on MNIST-01 with PCD-100 for 10 000 steps, using 200 hidden nodes and 2000 permanent chains:
89
+
64
90
  ```bash
65
- rbms train -d ./data/MNIST.h5 --subset_labels 0 1 --num_hiddens 200 --gibbs_steps 100 --num_chains 2000 --num_updates 10000 --filename ./RBM_MNIST01.h5
91
+ rbms train -d ./data/MNIST.h5 --subset_labels 0 1 \
92
+ --num_hiddens 200 --gibbs_steps 100 --num_chains 2000 \
93
+ --num_updates 10000 --filename ./RBM_MNIST01.h5
66
94
  ```
67
95
 
68
96
  ## Documentation
@@ -73,16 +101,17 @@ The documentation is available at [https://dsysdml.github.io/rbms/](https://dsys
73
101
 
74
102
  We welcome contributions to the development of TorchRBM. Here's how you can contribute:
75
103
 
76
- - **Fork the Repository**: Fork the main repository and make your changes.
77
- - **Propose a Merge Request**: Once your changes are complete, propose a merge request.
78
- - **Testing**: Ensure your code is tested using the pytest framework. Include your tests in the tests folder.
79
- - **Code Style**: Follow the pre-commit configuration for code style.
80
- - **Documentation**: Document your code using the Google docstring style and provide type hints .
81
- - **Dependencies**: Avoid adding extra dependencies unless absolutely necessary.
104
+ - **Fork the Repository**: Fork the main repository and make your changes.
105
+ - **Propose a Merge Request**: Once your changes are complete, propose a merge request.
106
+ - **Testing**: Ensure your code is tested using the pytest framework. Include your tests in the tests folder.
107
+ - **Code Style**: Follow the pre-commit configuration for code style.
108
+ - **Documentation**: Document your code using the Google docstring style and provide type hints .
109
+ - **Dependencies**: Avoid adding extra dependencies unless absolutely necessary.
82
110
 
83
111
  ## Support
84
112
 
85
113
  If you encounter any issues, please open an issue on the main repository.
86
114
 
87
115
  ## License
88
- `rbms` is released under the MIT License.
116
+
117
+ `rbms` is released under the MIT License.
rbms-0.2.0/README.md ADDED
@@ -0,0 +1,95 @@
1
+ [![codecov](https://codecov.io/gh/DsysDML/rbms/graph/badge.svg?token=HRWJLZRBDD)](https://codecov.io/gh/DsysDML/rbms)
2
+ [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
3
+ ![Static Badge](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-green)
4
+
5
+ # RBMs
6
+
7
+ ## Overview
8
+
9
+ `rbms` is a GPU-accelerated package designed to train and analyze Restricted Boltzmann Machines (RBMs). It is intended for students and researchers who need an efficient tool for working with RBMs.
10
+ Features:
11
+
12
+ - GPU Acceleration through PyTorch.
13
+ - Multiple RBM Types: Supports Bernoulli-Bernoulli RBM and Potts-Bernoulli RBM.
14
+ - Extensible Design: Provides an abstract class RBM with methods that can be implemented for new types of RBMs, minimizing the need to reimplement training algorithms, analysis methods, and sampling methods.
15
+
16
+ ## Installation
17
+
18
+ ### PyPI
19
+
20
+ `rbms` can be installed from PyPI:
21
+
22
+ ```bash
23
+ pip install rbms
24
+ ```
25
+
26
+ The last version on PyPI corresponds to the main branch of this repo. To update the installed package run
27
+
28
+ ```bash
29
+ pip install rbms --upgrade
30
+ ```
31
+
32
+ ### Github
33
+
34
+ If you want a more up-to-date version or wish to contribute, you can install the package directly from this repository:
35
+
36
+ ```bash
37
+ git clone git@github.com:DsysDML/rbms.git
38
+ cd rbms && pip install -e .
39
+ ```
40
+
41
+ If you want to update the package run
42
+
43
+ ```bash
44
+ git pull
45
+ ```
46
+
47
+ from inside the cloned repo.
48
+
49
+ ## Dependencies
50
+
51
+ The dependencies are included in the pyproject.toml file and should be compiled in the wheel distribution. If you have a GPU, make sure to install PyTorch with GPU support.
52
+
53
+ ## Usage
54
+
55
+ Main Classes and Functions:
56
+
57
+ - `EBM`: An abstract class that provides the basic structure and methods for Energy-Based Models (EBMs).
58
+ - `RBM`: An abstract class that provides the basic structure and methods for RBMs.
59
+ - `BBRBM`: A concrete implementation of the Bernoulli-Bernoulli RBM.
60
+ - `PBRBM`: A concrete implementation of the Potts-Bernoulli RBM.
61
+ - `rbms.sampling`: Submodule for sampling methods.
62
+ - `rbms.training`: Submodule for training algorithms.
63
+
64
+ ## Basic Example
65
+
66
+ Train a RBM on MNIST-01 with PCD-100 for 10 000 steps, using 200 hidden nodes and 2000 permanent chains:
67
+
68
+ ```bash
69
+ rbms train -d ./data/MNIST.h5 --subset_labels 0 1 \
70
+ --num_hiddens 200 --gibbs_steps 100 --num_chains 2000 \
71
+ --num_updates 10000 --filename ./RBM_MNIST01.h5
72
+ ```
73
+
74
+ ## Documentation
75
+
76
+ The documentation is available at [https://dsysdml.github.io/rbms/](https://dsysdml.github.io/rbms/)
77
+
78
+ ## Contributing
79
+
80
+ We welcome contributions to the development of TorchRBM. Here's how you can contribute:
81
+
82
+ - **Fork the Repository**: Fork the main repository and make your changes.
83
+ - **Propose a Merge Request**: Once your changes are complete, propose a merge request.
84
+ - **Testing**: Ensure your code is tested using the pytest framework. Include your tests in the tests folder.
85
+ - **Code Style**: Follow the pre-commit configuration for code style.
86
+ - **Documentation**: Document your code using the Google docstring style and provide type hints .
87
+ - **Dependencies**: Avoid adding extra dependencies unless absolutely necessary.
88
+
89
+ ## Support
90
+
91
+ If you encounter any issues, please open an issue on the main repository.
92
+
93
+ ## License
94
+
95
+ `rbms` is released under the MIT License.
@@ -613,6 +613,20 @@
613
613
  "module_short": "rbms",
614
614
  "name": "RBM.init_chains"
615
615
  },
616
+ {
617
+ "is_class": false,
618
+ "is_explicit": false,
619
+ "module": "rbms.classes",
620
+ "module_short": "rbms.classes",
621
+ "name": "EBM.init_chains"
622
+ },
623
+ {
624
+ "is_class": false,
625
+ "is_explicit": false,
626
+ "module": "rbms",
627
+ "module_short": "rbms",
628
+ "name": "EBM.init_chains"
629
+ },
616
630
  {
617
631
  "is_class": false,
618
632
  "is_explicit": false,
@@ -179,7 +179,7 @@
179
179
  "name": "python",
180
180
  "nbconvert_exporter": "python",
181
181
  "pygments_lexer": "ipython3",
182
- "version": "3.13.0"
182
+ "version": "3.12.7"
183
183
  }
184
184
  },
185
185
  "nbformat": 4,
@@ -0,0 +1 @@
1
+ 21caaed3471ff131aeda19a34e85cc5d
@@ -19,7 +19,7 @@
19
19
 
20
20
 
21
21
  Analyze a post-training Bernoulli-Bernoulli RBM
22
- ======================================================
22
+ ===========================
23
23
 
24
24
  This script shows how to analyze the RBM after having trained it.
25
25
 
@@ -281,7 +281,7 @@ We can now sample those chains and compare again the distribution
281
281
  .. GENERATED FROM PYTHON SOURCE LINES 115-118
282
282
 
283
283
  Compute the AIS estimation of the log-likelihood.
284
- --------------------------------------------------------
284
+ ------------------------------
285
285
  For now, we only looked at a qualitative evaluation of the model
286
286
 
287
287
  .. GENERATED FROM PYTHON SOURCE LINES 118-128
@@ -306,7 +306,7 @@ For now, we only looked at a qualitative evaluation of the model
306
306
 
307
307
  .. code-block:: none
308
308
 
309
- -389.85870361328125
309
+ -387.64599609375
310
310
 
311
311
 
312
312
 
@@ -314,7 +314,7 @@ For now, we only looked at a qualitative evaluation of the model
314
314
 
315
315
  .. rst-class:: sphx-glr-timing
316
316
 
317
- **Total running time of the script:** (0 minutes 6.944 seconds)
317
+ **Total running time of the script:** (0 minutes 8.271 seconds)
318
318
 
319
319
 
320
320
  .. _sphx_glr_download_auto_examples_plot_generated_samples.py:
@@ -6,7 +6,7 @@
6
6
 
7
7
  Computation times
8
8
  =================
9
- **00:06.944** total execution time for 1 file **from auto_examples**:
9
+ **00:08.271** total execution time for 1 file **from auto_examples**:
10
10
 
11
11
  .. container::
12
12
 
@@ -33,5 +33,5 @@ Computation times
33
33
  - Time
34
34
  - Mem (MB)
35
35
  * - :ref:`sphx_glr_auto_examples_plot_generated_samples.py` (``plot_generated_samples.py``)
36
- - 00:06.944
36
+ - 00:08.271
37
37
  - 0.0
@@ -1,4 +1,4 @@
1
- # Welcome to TorchRBM
1
+ # Welcome to Restricted Boltzmann Machines (RBM) in PyTorch
2
2
 
3
3
  `rbms` is a GPU-accelerated package designed to train and analyze Restricted Boltzmann Machines (RBMs). It is intended for students and researchers who need an efficient tool for working with RBMs.
4
4
 
@@ -8,23 +8,22 @@
8
8
  - **Multiple RBM Types**: Supports Bernoulli-Bernoulli RBM and Potts-Bernoulli RBM.
9
9
  - **Extensible Design**: Provides an abstract class `RBM` with methods that can be implemented for new types of RBMs, minimizing the need to reimplement training algorithms, analysis methods, and sampling methods.
10
10
 
11
-
12
11
  ## Installation
13
12
 
14
- To install TorchRBM, you can use pip:
13
+ To install `rbms`, you can use pip:
15
14
 
16
15
  ```bash
17
- pip install .
16
+ pip install rbms
18
17
  ```
19
18
 
20
- ## What's New
21
- ### Version 0.1
19
+ ## [What's New](whats_new.rst)
20
+
21
+ ### Version 0.2
22
+
23
+ - EBM abstract class for more generic EBMs.
24
+ -
22
25
 
23
- - Initial release of TorchRBM.
24
- - Support for Bernoulli-Bernoulli RBM and Potts-Bernoulli RBM.
25
- - Abstract class RBM for easy extension to new RBM types.
26
- - GPU acceleration for training and analysis.
27
- - Comprehensive sampling and training submodules.
26
+ See [Releases](https://github.com/DsysDML/rbms/releases)
28
27
 
29
28
  ## [Restricted Boltzmann Machines](rbm.md)
30
29
 
@@ -34,10 +33,7 @@ pip install .
34
33
 
35
34
  ## [API](api.md)
36
35
 
37
-
38
-
39
36
  ```{toctree}
40
37
  :caption: 'Contents:'
41
38
  :maxdepth: 4
42
39
  ```
43
-
@@ -6,7 +6,7 @@
6
6
 
7
7
  Computation times
8
8
  =================
9
- **00:06.944** total execution time for 1 file **from all galleries**:
9
+ **00:08.271** total execution time for 1 file **from all galleries**:
10
10
 
11
11
  .. container::
12
12
 
@@ -33,5 +33,5 @@ Computation times
33
33
  - Time
34
34
  - Mem (MB)
35
35
  * - :ref:`sphx_glr_auto_examples_plot_generated_samples.py` (``../../examples/plot_generated_samples.py``)
36
- - 00:06.944
36
+ - 00:08.271
37
37
  - 0.0
@@ -31,9 +31,8 @@ with h5py.File("my_dataset.h5", "w") as f:
31
31
  ## Command line arguments
32
32
 
33
33
  When running a script requiring a dataset, you have several flags:
34
- - `-d` or `--data` The path to the dataset. It can either be the full or relative path to the .h5/fasta file (`-d ./data/dataset.h5`) or, if it's an included dataset (check ), you can just use the key of the dataset (`-d HGD` will load the Human Genome Dataset`).
35
- - `--variable_type` Can be one of `Bernoulli`, `Ising`, `Continuous`or `Potts`.
36
- - `--subset_labels` For datasets with labels specified, it allows to select only a subset of the dataset matching the specified labels. For example setting `-d MNIST --subset_labels 0 1` will load the $0$ and $1$ digits of the MNIST dataset (what we refer to as `MNIST-01` dataset)
34
+ - `-d` or `--data` The path to the dataset (e.g.`-d ./data/dataset.h5`).
35
+ - `--subset_labels` For datasets with labels specified, it allows to select only a subset of the dataset matching the specified labels. For example setting `-d MNIST --subset_labels 0 1` will load the $0$ and $1$ digits of the MNIST dataset (what we refer to as `MNIST-01` dataset). If specified in a dataset without labels, the full dataset is selected.
37
36
  - `--train_size` The proportion of the dataset to use as training dataset. It can go from $0$ to $1$ and the default is $0.6$.
38
37
  - `--test_size` Same as above, but for the test dataset. Defaults to $1-$ train size
39
38
  - `--use_weights` Compute the weights for protein sequences.
@@ -0,0 +1,51 @@
1
+ # Train a RBM
2
+
3
+ To train a RBM, you need to use the rbms train script.
4
+
5
+ ## RBM hyperparameters
6
+
7
+ - `--num_hiddens` Number of hidden nodes for the RBM. Setting it to $20$ or less allows to recover the exact log-likelihood of the model by enumerating on all hidden configurations.
8
+ - `--batch_size` Batch size, defaults to $2000$. Changing the batch size has an impact on the noise in the estimation of the positive term of the gradient. Setting it to a low value can lead to a very bad estimation and a bad training, but setting it too high can lead to an exact gradient, losing the benefits of the SGD (and remain trapped in a local minima for example).
9
+ - `--num_chains` Number of parallel chains, defaults to $2000$. Setting it to a much higher value than the batch size does not provide benefits, since it only impacts the estimation of the negative term of the gradient.
10
+ - `--gibbs_steps` Number of sampling steps performed at each gradient update. The $k$ in PCD-$k$.
11
+ - `--learning_rate` Learning rate. Defaults to $0.01$, setting a larger learning rate often leads to instability.
12
+ - `--num_updates` The training time is indexed on the number of gradient updates performed and not the number of epochs.
13
+ - `--beta` The inverse temperature to use during training (Defaults to $1$ and should not be changed)
14
+
15
+ ## Save options
16
+
17
+ - `--filename` The path to the hdf5 archive to save the RBM during training. It will overwrite previously existing file.
18
+ - `--n_save` The number of machines to save during the training.
19
+ - `--spacing` Can be `exp` or `linear`, defaults to `exp`. When `exp` is selected, the time between the save of two models will increase exponentially. (It will look good in log-scale). When `linear` is selected, the time between the save of two models will be constant.
20
+ Saving lots of models can quickly become the computational bottleneck, leading to long execution times.
21
+ - `--log` For now it is deprecated so you don't care about it.
22
+ - `--acc_ptt` Target acceptance rate. Defaults to $0.25$. Models will be saved when the acceptance rate between two consecutive models when sampling them using PTT drops below this threshold.
23
+ - `--acc_ll` Same as before but defaults to $0.75$. This allows to have two different schemes when saving models.
24
+
25
+ ## PyTorch options
26
+
27
+ - `--device` The device on which to run the computations. Follows the PyTorch semantic so you can select which GPU to use with 'cuda:1' for example.
28
+ - `--dtype` The dtype of all the tensors. can be `int`, `double` or `float`. The default is `float` which corresponds to `torch.float32`.
29
+
30
+ ## Example
31
+
32
+ The command I typically use to train a RBM on `MNIST-01` will be
33
+
34
+ ```bash
35
+ rbms train -d ./path/to/MNIST.h5 --subset_labels 0 1 \
36
+ --filename output/rbm/MNIST01_from_scratch.h5 --num_updates 10000 \
37
+ --n_save 50 --spacing exp --num_hiddens 20 --batch_size 2000 --num_chains 2000 \
38
+ --learning_rate 0.01 --device cuda --dtype float
39
+ ```
40
+
41
+ # Restore the training
42
+
43
+ If you want to continue the training of a RBM (be it one recovered from a RCM or a previously trained one), you can use the same scripts. The differences are that you should add the `--restore` flags. Also some arguments are not useful anymore and can be safely ignored:
44
+
45
+ - `--num_hiddens`
46
+ - `--batch_size`
47
+ - `--gibbs_steps`
48
+ - `--learning_rate`
49
+ - `--num_chains`
50
+
51
+ Finally the updates will be added to the same archive you provide as an input through `--filename`. If the `--restore` flag is set, then the file will **not** be overwritten.
@@ -1,6 +1,6 @@
1
1
  """
2
2
  Analyze a post-training Bernoulli-Bernoulli RBM
3
- ======================================================
3
+ ===========================
4
4
 
5
5
  This script shows how to analyze the RBM after having trained it.
6
6
  """
@@ -113,7 +113,7 @@ plot_PCA(
113
113
 
114
114
  # %%
115
115
  # Compute the AIS estimation of the log-likelihood.
116
- # --------------------------------------------------------
116
+ # ------------------------------
117
117
  # For now, we only looked at a qualitative evaluation of the model
118
118
  from rbms.partition_function.ais import compute_partition_function_ais
119
119
  from rbms.utils import compute_log_likelihood
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "rbms"
7
- version = "0.1"
7
+ version = "0.2.0"
8
8
  authors = [
9
9
  {name="Nicolas Béreux", email="nicolas.bereux@gmail.com"},
10
10
  {name="Aurélien Decelle"},
@@ -22,9 +22,7 @@ requires-python = ">=3.11"
22
22
  dependencies = [
23
23
  "h5py>=3.12.0",
24
24
  "numpy>=2.0.0, <=2.1.2",
25
- "seaborn>=0.13.0",
26
25
  "matplotlib>=3.8.0",
27
- "scikit-learn==1.5.2",
28
26
  "torch>=2.0.0, <=2.5.0",
29
27
  "tqdm>=4.65.0",
30
28
  ]
@@ -110,7 +110,7 @@ class BBRBM(RBM):
110
110
  mh_data=data["hidden_mag"],
111
111
  w_data=data["weights"],
112
112
  v_chain=chains["visible"],
113
- h_chain=chains["hidden"],
113
+ h_chain=chains["hidden_mag"],
114
114
  w_chain=chains["weights"],
115
115
  vbias=self.vbias,
116
116
  hbias=self.hbias,