Squashed commit of the following:

commit c451e67
Author: ian <tycheng@nus.edu.sg>
Date:   Tue Oct 8 11:17:54 2024 +0800

    dvine: s_first can be in the middle! sim: sobol seq

    dvine: TSP with precedence constraints or clustered TSP
    cvine/rvine: min heap
    DataBiCop.sim: is_sobol
    DataVineCop.sim: is_sobol

LICENSE

@@ -632,7 +632,7 @@ state the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
 
     torchvinecopulib, a vine copula package using PyTorch
-    Copyright (C) 2024-  Tuoyuan Cheng, Xiaosheng You, Kan Chen
+    Copyright (C) 2024-  Tuoyuan Cheng, Kan Chen
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
@@ -652,7 +652,7 @@ Also add information on how to contact you by electronic and paper mail.
 If the program does terminal interaction, make it output a short
 notice like this when it starts in an interactive mode:
 
-    torchvinecopulib  Copyright (C) 2024-  Tuoyuan Cheng, Xiaosheng You, Kan Chen
+    torchvinecopulib  Copyright (C) 2024-  Tuoyuan Cheng, Kan Chen
     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

README.md

@@ -5,15 +5,13 @@
 [![Lint Pytest](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/python-package.yml)
 [![Deploy Docs](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/static.yml/badge.svg?branch=main)](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/static.yml)
 
-[![Python Version](https://img.shields.io/badge/Python-%203.10%7C3.11%7C3.12-blue)](https://devguide.python.org/versions/#versions)
-[![OS](https://img.shields.io/badge/OS-Windows%7CmacOS%7CUbuntu-blue
-)](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/python-package.yml)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/torchvinecopulib)
+[![OS](https://img.shields.io/badge/OS-Windows%7CmacOS%7CUbuntu-blue)](https://github.com/TY-Cheng/torchvinecopulib/actions/workflows/python-package.yml)
 
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![PyPI - Version](https://img.shields.io/pypi/v/torchvinecopulib?style=flat)](https://pypi.org/project/torchvinecopulib/)
+![GitHub License](https://img.shields.io/github/license/ty-cheng/torchvinecopulib)
+![PyPI - Version](https://img.shields.io/pypi/v/torchvinecopulib)
 [![DOI](https://zenodo.org/badge/768037665.svg)](https://zenodo.org/doi/10.5281/zenodo.10836953)
 
-
 Yet another vine copula package, using [PyTorch](https://pytorch.org/get-started/locally/).
 
 - C/D/R-Vine full-simulation/ quantile-regression/ conditional-simulation, all in one package
@@ -28,7 +26,7 @@ Yet another vine copula package, using [PyTorch](https://pytorch.org/get-started
 
 ```toml
 # inside the `./pyproject.toml` file;
-numpy = "<2"
+numpy = "*"
 python = "^3.10"
 scipy = "*"
 # optional to facilitate customization
@@ -49,32 +47,35 @@ python -c "import torch; print(torch.cuda.is_available())"
 ## Installation
 
 - By `pip` from [`PyPI`](https://pypi.org/project/torchvinecopulib/):
+
 ```bash
 pip install torchvinecopulib torch
 ```
+
 - Or with full drawing and bivariate dependency metric support:
 
 ```bash
 pip install torchvinecopulib torch matplotlib pot scikit-learn
 ```
 
 - Or `pip` from `./dist/*.whl` or `./dist/*.tar.gz` in this repo.
-Need to use proper file name.
+  Need to use proper file name.
 
 ```bash
 # inside project root folder
-pip install ./dist/torchvinecopulib-2024.9.0-py3-none-any.whl
+pip install ./dist/torchvinecopulib-2024.10.0-py3-none-any.whl
 # or
-pip install ./dist/torchvinecopulib-2024.9.0.tar.gz
+pip install ./dist/torchvinecopulib-2024.10.0.tar.gz
 ```
 
 ### (Optional) [Poetry](https://python-poetry.org/docs/) for Dependency Management and Packaging
+
 After `git clone https://github.com/TY-Cheng/torchvinecopulib.git`, `cd` into the project root where [`pyproject.toml`](https://github.com/TY-Cheng/torchvinecopulib/blob/main/pyproject.toml) exists,
 
 ```bash
 # inside project root folder
 poetry lock && poetry install -E dev_cpu --with dev_cpu --sync
-# or 
+# or
 poetry lock && poetry install -E dev_cuda --with dev_cuda --sync
 ```
 
@@ -110,6 +111,7 @@ coverage run -m pytest ./tests && coverage html
 ```
 
 ## TODO
+
 - more (non-parametric) `bicop` class in `torch`
 - port to TensorFlow Probability for `cuda`-compatible [Student's t cdf/ppf](https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/StudentT)
 
@@ -136,10 +138,9 @@ We welcome contributions, whether it's a bug report, feature suggestion, code co
 - [in-place ops can be slower](https://discuss.pytorch.org/t/are-inplace-operations-faster/61209/4)
 - [torch.jit.script can be slower](https://discuss.pytorch.org/t/why-is-torch-jit-script-slower/120131/6)
 
-
 ## License
 
-> Copyright (C) 2024 Tuoyuan Cheng, Xiaosheng You, Kan Chen
+> Copyright (C) 2024- Tuoyuan Cheng, Kan Chen
 >
 > This file is part of torchvinecopulib.
 > torchvinecopulib is free software: you can redistribute it and/or modify

docs/_build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: e36efb9701b42e97c69e435b920b8c9f
+config: fd7ece03e391b3f3cb0331c9f87c12ae
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/html/_modules/index.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" />
 
     <!-- Generated with Sphinx 8.0.2 and Furo 2024.08.06 -->
-        <title>Overview: module code - torchvinecopulib 2024.9.0 documentation</title>
+        <title>Overview: module code - torchvinecopulib 2024.10.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?v=354aac6f" />
     <link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?v=302659d7" />
@@ -17,18 +17,24 @@
   body {
     --color-code-background: #f8f8f8;
   --color-code-foreground: black;
+  --color-brand-primary: #007acc;
+  --color-brand-content: #007acc;
 
   }
   @media not print {
     body[data-theme="dark"] {
       --color-code-background: #202020;
   --color-code-foreground: #d0d0d0;
+  --color-brand-primary: #007acc;
+  --color-brand-content: #007acc;
 
     }
     @media (prefers-color-scheme: dark) {
       body:not([data-theme="light"]) {
         --color-code-background: #202020;
   --color-code-foreground: #d0d0d0;
+  --color-brand-primary: #007acc;
+  --color-brand-content: #007acc;
 
       }
     }
@@ -165,7 +171,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../index.html"><div class="brand">torchvinecopulib 2024.9.0 documentation</div></a>
+      <a href="../index.html"><div class="brand">torchvinecopulib 2024.10.0 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -189,7 +195,6 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../index.html">
 
 
-  <span class="sidebar-brand-text">torchvinecopulib 2024.9.0 documentation</span>
 
 </a><form class="sidebar-search-container" method="get" action="../search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -281,7 +286,7 @@ <h1>All modules for which code is available</h1>
 
     </aside>
   </div>
-</div><script src="../_static/documentation_options.js?v=a0cfb6c8"></script>
+</div><script src="../_static/documentation_options.js?v=2443068e"></script>
     <script src="../_static/doctools.js?v=9a2dae69"></script>
     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/scripts/furo.js?v=5fa4622c"></script>

docs/_build/html/_modules/torchvinecopulib/bicop/_clayton.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../../genindex.html" /><link rel="search" title="Search" href="../../../search.html" />
 
     <!-- Generated with Sphinx 8.0.2 and Furo 2024.08.06 -->
-        <title>torchvinecopulib.bicop._clayton - torchvinecopulib 2024.9.0 documentation</title>
+        <title>torchvinecopulib.bicop._clayton - torchvinecopulib 2024.10.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="../../../_static/styles/furo.css?v=354aac6f" />
     <link rel="stylesheet" type="text/css" href="../../../_static/styles/furo-extensions.css?v=302659d7" />
@@ -17,18 +17,24 @@
   body {
     --color-code-background: #f8f8f8;
   --color-code-foreground: black;
+  --color-brand-primary: #007acc;
+  --color-brand-content: #007acc;
 
   }
   @media not print {
     body[data-theme="dark"] {
       --color-code-background: #202020;
   --color-code-foreground: #d0d0d0;
+  --color-brand-primary: #007acc;
+  --color-brand-content: #007acc;
 
     }
     @media (prefers-color-scheme: dark) {
       body:not([data-theme="light"]) {
         --color-code-background: #202020;
   --color-code-foreground: #d0d0d0;
+  --color-brand-primary: #007acc;
+  --color-brand-content: #007acc;
 
       }
     }
@@ -165,7 +171,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../../index.html"><div class="brand">torchvinecopulib 2024.9.0 documentation</div></a>
+      <a href="../../../index.html"><div class="brand">torchvinecopulib 2024.10.0 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -189,7 +195,6 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../../index.html">
 
 
-  <span class="sidebar-brand-text">torchvinecopulib 2024.9.0 documentation</span>
 
 </a><form class="sidebar-search-container" method="get" action="../../../search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -347,7 +352,7 @@ <h1>Source code for torchvinecopulib.bicop._clayton</h1><div class="highlight"><
 
     </aside>
   </div>
-</div><script src="../../../_static/documentation_options.js?v=a0cfb6c8"></script>
+</div><script src="../../../_static/documentation_options.js?v=2443068e"></script>
     <script src="../../../_static/doctools.js?v=9a2dae69"></script>
     <script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../../_static/scripts/furo.js?v=5fa4622c"></script>

docs/_build/html/_modules/torchvinecopulib/bicop/_data_bcp.html

@@ -5,7 +5,7 @@
     <meta name="color-scheme" content="light dark"><link rel="index" title="Index" href="../../../genindex.html" /><link rel="search" title="Search" href="../../../search.html" />
 
     <!-- Generated with Sphinx 8.0.2 and Furo 2024.08.06 -->
-        <title>torchvinecopulib.bicop._data_bcp - torchvinecopulib 2024.9.0 documentation</title>
+        <title>torchvinecopulib.bicop._data_bcp - torchvinecopulib 2024.10.0 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=a746c00c" />
     <link rel="stylesheet" type="text/css" href="../../../_static/styles/furo.css?v=354aac6f" />
     <link rel="stylesheet" type="text/css" href="../../../_static/styles/furo-extensions.css?v=302659d7" />
@@ -17,18 +17,24 @@
   body {
     --color-code-background: #f8f8f8;
   --color-code-foreground: black;
+  --color-brand-primary: #007acc;
+  --color-brand-content: #007acc;
 
   }
   @media not print {
     body[data-theme="dark"] {
       --color-code-background: #202020;
   --color-code-foreground: #d0d0d0;
+  --color-brand-primary: #007acc;
+  --color-brand-content: #007acc;
 
     }
     @media (prefers-color-scheme: dark) {
       body:not([data-theme="light"]) {
         --color-code-background: #202020;
   --color-code-foreground: #d0d0d0;
+  --color-brand-primary: #007acc;
+  --color-brand-content: #007acc;
 
       }
     }
@@ -165,7 +171,7 @@
       </label>
     </div>
     <div class="header-center">
-      <a href="../../../index.html"><div class="brand">torchvinecopulib 2024.9.0 documentation</div></a>
+      <a href="../../../index.html"><div class="brand">torchvinecopulib 2024.10.0 documentation</div></a>
     </div>
     <div class="header-right">
       <div class="theme-toggle-container theme-toggle-header">
@@ -189,7 +195,6 @@
       <div class="sidebar-sticky"><a class="sidebar-brand" href="../../../index.html">
 
 
-  <span class="sidebar-brand-text">torchvinecopulib 2024.9.0 documentation</span>
 
 </a><form class="sidebar-search-container" method="get" action="../../../search.html" role="search">
   <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search">
@@ -243,7 +248,6 @@ <h1>Source code for torchvinecopulib.bicop._data_bcp</h1><div class="highlight">
 <span class="kn">from</span> <span class="nn">enum</span> <span class="kn">import</span> <span class="n">Enum</span>
 <span class="kn">from</span> <span class="nn">pprint</span> <span class="kn">import</span> <span class="n">pformat</span>
 
-
 <span class="kn">import</span> <span class="nn">torch</span>
 
 <span class="kn">from</span> <span class="nn">._abc</span> <span class="kn">import</span> <span class="n">BiCopAbstract</span>
@@ -500,23 +504,32 @@ <h1>Source code for torchvinecopulib.bicop._data_bcp</h1><div class="highlight">
         <span class="n">seed</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
         <span class="n">device</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;cpu&quot;</span><span class="p">,</span>
         <span class="n">dtype</span><span class="p">:</span> <span class="n">torch</span><span class="o">.</span><span class="n">dtype</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">float64</span><span class="p">,</span>
+        <span class="n">is_sobol</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
     <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">torch</span><span class="o">.</span><span class="n">Tensor</span><span class="p">:</span>
-<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="w">        </span><span class="sd">&quot;&quot;&quot;Simulates random samples from a bivariate copula model.</span>
 
-<span class="sd">        :param self: an instance of the DataBiCop dataclass</span>
-<span class="sd">        :param num_sim: number of simulations</span>
+<span class="sd">        :param num_sim: Number of samples to simulate.</span>
 <span class="sd">        :type num_sim: int</span>
-<span class="sd">        :param seed: random seed for torch.manual_seed(), defaults to 0</span>
+<span class="sd">        :param seed: Random seed for reproducibility. Defaults to 0.</span>
 <span class="sd">        :type seed: int, optional</span>
-<span class="sd">        :param device: device for torch.rand(), defaults to &#39;cpu&#39;</span>
+<span class="sd">        :param device: Device to perform the computation (&#39;cpu&#39; or &#39;cuda&#39;). Defaults to &quot;cpu&quot;.</span>
 <span class="sd">        :type device: str, optional</span>
-<span class="sd">        :param dtype: data type for torch.rand(), defaults to torch.float64</span>
+<span class="sd">        :param dtype: Data type of the generated samples. Defaults to torch.float64.</span>
 <span class="sd">        :type dtype: torch.dtype, optional</span>
-<span class="sd">        :return: simulated observation of the bivariate copula, of shape (num_sim, 2)</span>
+<span class="sd">        :param is_sobol: If True, uses Sobol sequence for quasi-random number generation. Defaults to False.</span>
+<span class="sd">        :type is_sobol: bool, optional</span>
+<span class="sd">        :return: A tensor of shape (num_sim, 2) containing the simulated samples.</span>
 <span class="sd">        :rtype: torch.Tensor</span>
 <span class="sd">        &quot;&quot;&quot;</span>
-        <span class="n">torch</span><span class="o">.</span><span class="n">manual_seed</span><span class="p">(</span><span class="n">seed</span><span class="o">=</span><span class="n">seed</span><span class="p">)</span>
-        <span class="n">obs</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">rand</span><span class="p">(</span><span class="n">size</span><span class="o">=</span><span class="p">(</span><span class="n">num_sim</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="n">device</span><span class="o">=</span><span class="n">device</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">dtype</span><span class="p">)</span>
+        <span class="k">if</span> <span class="n">is_sobol</span><span class="p">:</span>
+            <span class="n">obs</span> <span class="o">=</span> <span class="p">(</span>
+                <span class="n">torch</span><span class="o">.</span><span class="n">quasirandom</span><span class="o">.</span><span class="n">SobolEngine</span><span class="p">(</span><span class="n">dimension</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">scramble</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">seed</span><span class="o">=</span><span class="n">seed</span><span class="p">)</span>
+                <span class="o">.</span><span class="n">draw</span><span class="p">(</span><span class="n">n</span><span class="o">=</span><span class="n">num_sim</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">dtype</span><span class="p">)</span>
+                <span class="o">.</span><span class="n">to</span><span class="p">(</span><span class="n">device</span><span class="p">)</span>
+            <span class="p">)</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="n">torch</span><span class="o">.</span><span class="n">manual_seed</span><span class="p">(</span><span class="n">seed</span><span class="o">=</span><span class="n">seed</span><span class="p">)</span>
+            <span class="n">obs</span> <span class="o">=</span> <span class="n">torch</span><span class="o">.</span><span class="n">rand</span><span class="p">(</span><span class="n">size</span><span class="o">=</span><span class="p">(</span><span class="n">num_sim</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="n">device</span><span class="o">=</span><span class="n">device</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">dtype</span><span class="p">)</span>
         <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">fam</span> <span class="o">!=</span> <span class="s2">&quot;Independent&quot;</span><span class="p">:</span>
             <span class="n">obs</span><span class="p">[:,</span> <span class="p">[</span><span class="mi">1</span><span class="p">]]</span> <span class="o">=</span> <span class="n">ENUM_FAM_BICOP</span><span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">fam</span><span class="p">]</span><span class="o">.</span><span class="n">value</span><span class="o">.</span><span class="n">hinv1</span><span class="p">(</span>
                 <span class="n">obs</span><span class="o">=</span><span class="n">obs</span><span class="p">,</span>
@@ -558,7 +571,7 @@ <h1>Source code for torchvinecopulib.bicop._data_bcp</h1><div class="highlight">
 
     </aside>
   </div>
-</div><script src="../../../_static/documentation_options.js?v=a0cfb6c8"></script>
+</div><script src="../../../_static/documentation_options.js?v=2443068e"></script>
     <script src="../../../_static/doctools.js?v=9a2dae69"></script>
     <script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../../_static/scripts/furo.js?v=5fa4622c"></script>