optiviz 0.1.0__tar.gz

optiviz-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ronit Kunkolienker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights  
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+copies of the Software, and to permit persons to whom the Software is  
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all  
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE  
+SOFTWARE.

optiviz-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: optiviz
+Version: 0.1.0
+Summary: Educational tool for visualizing PyTorch-compatible optimisers on any differentiable 1D or 2D function.
+Author-email: Ronit Kunkolienker <ronitkunk@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Ronit Kunkolienker
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights  
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+        copies of the Software, and to permit persons to whom the Software is  
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all  
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE  
+        SOFTWARE.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: torch
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Dynamic: license-file
+
+# OptiViz
+OptiViz enables effortless visualisation of the optimisation sequence of *any* PyTorch optimiser on *any* differentiable function in one or two variables. OptiViz might find educational use in introductory nonlinear optimisation or deep learning classes.
+
+![Vanilla gradient descent minimising a convex quadratic form.](sgd.png "SGD")
+
+# Installation
+To install OptiViz, please use:
+```sh
+pip install optiviz
+```
+
+# Usage
+All functionality of OptiViz is exposed through the `optiviz.optimise` function.
+```python
+import torch
+from optiviz import optimise
+```
+Any optimisation problem has an objective function. OptiViz works with differentiable, real-valued objective functions in one or two variables.
+```math
+f : \mathbb{R} \rightarrow \mathbb{R}
+```
+```math
+g : \mathbb{R}^2 \rightarrow \mathbb{R}
+```
+In code, every input and output to the objective function must be a `torch.Tensor` of shape `(1,)`
+```python
+def f(x: torch.Tensor) -> torch.Tensor:
+    """
+    Example of an objective function in one variable.
+    """
+    return x ** 2
+def g(x: torch.Tensor, y: torch.Tensor) -> torch.Tensor:
+    """
+    Example of an objective function in two variables.
+    """
+    return x ** 2 + y ** 2 + x.sin() * y.sin()
+```
+The `optiviz.optimise` function (please see docstring) is used to visualise the optimisation sequence of the objective function using a PyTorch optimiser.
+```python
+arg_g_min = optimise(
+        g, # objective function
+        (12.5, 12.5), # initial values of the parameters being adjusted
+        plot_boundary=25,
+        iters=100,
+        optimiser=torch.optim.Adam, # PyTorch-compatible optimiser
+        lr=5e-1
+    )
+```

optiviz-0.1.0/README.md

@@ -0,0 +1,48 @@
+# OptiViz
+OptiViz enables effortless visualisation of the optimisation sequence of *any* PyTorch optimiser on *any* differentiable function in one or two variables. OptiViz might find educational use in introductory nonlinear optimisation or deep learning classes.
+
+![Vanilla gradient descent minimising a convex quadratic form.](sgd.png "SGD")
+
+# Installation
+To install OptiViz, please use:
+```sh
+pip install optiviz
+```
+
+# Usage
+All functionality of OptiViz is exposed through the `optiviz.optimise` function.
+```python
+import torch
+from optiviz import optimise
+```
+Any optimisation problem has an objective function. OptiViz works with differentiable, real-valued objective functions in one or two variables.
+```math
+f : \mathbb{R} \rightarrow \mathbb{R}
+```
+```math
+g : \mathbb{R}^2 \rightarrow \mathbb{R}
+```
+In code, every input and output to the objective function must be a `torch.Tensor` of shape `(1,)`
+```python
+def f(x: torch.Tensor) -> torch.Tensor:
+    """
+    Example of an objective function in one variable.
+    """
+    return x ** 2
+def g(x: torch.Tensor, y: torch.Tensor) -> torch.Tensor:
+    """
+    Example of an objective function in two variables.
+    """
+    return x ** 2 + y ** 2 + x.sin() * y.sin()
+```
+The `optiviz.optimise` function (please see docstring) is used to visualise the optimisation sequence of the objective function using a PyTorch optimiser.
+```python
+arg_g_min = optimise(
+        g, # objective function
+        (12.5, 12.5), # initial values of the parameters being adjusted
+        plot_boundary=25,
+        iters=100,
+        optimiser=torch.optim.Adam, # PyTorch-compatible optimiser
+        lr=5e-1
+    )
+```

optiviz-0.1.0/optiviz/__init__.py

@@ -0,0 +1,3 @@
+from .optimise import optimise
+
+__all__ = ["optimise"]

optiviz-0.1.0/optiviz/optimise.py

@@ -0,0 +1,54 @@
+import torch
+from typing import Type
+import inspect
+import matplotlib.pyplot as plt
+
+from .visualise import plot_objective_1D, plot_point_1D, plot_objective_2D, plot_point_2D
+
+def optimise(fn, init_vector: tuple[float], plot_boundary: float=25, iters: int=1000, optimiser: Type[torch.optim.Optimizer]=torch.optim.Adam, **kwargs) -> tuple[float]:
+    """
+    Visualises the minimisation sequence of the given differentiable function `fn` using the given optimiser.
+    Arguments:
+        `fn` : The differentiable function to be minimised. Must take exactly 1 or 2 non-default arguments. Return value and each argument must be a `torch.Tensor` with shape (1,).
+        `init_vector`: A tuple of the same dimension as the number of arguments of `fn`, specifying the initial values of the function parameters.
+        `plot_boundary`: Length of the the plot boundary in all dimensions in the parameter space.
+        `iters`: Number of optimiser iterations; defaults to 1000.
+        `optimiser`: Optimisation algorithm to use. Must be a `torch.optim.Optimizer` subclass (not instance); defaults to Adam (https://arxiv.org/abs/1412.6980).
+        `**kwargs`: any keyword arguments for the optimiser; e.g. lr
+
+    Returns:
+        Depending on fn, a 1-tuple or 2-tuple of the estimated optimal parameters.
+    """
+    sig = inspect.signature(fn)
+    input_dim = sum(p.default == inspect._empty for p in sig.parameters.values())
+
+    assert input_dim==1 or input_dim==2, f"'fn' must take either 1 or 2 non-default arguments (received {input_dim})."
+    assert input_dim==len(init_vector), f"Number of non-default arguments of 'fn' ({input_dim}) does not match number of initial values in 'init_vector' ({len(init_vector)})."
+
+    x = tuple([torch.tensor([x_i], requires_grad=True) for x_i in init_vector])
+
+    plt.ion()
+    ax = None
+    if input_dim==1:
+        ax = plt.figure().add_subplot()
+        plot_objective_1D(ax, fn, (init_vector[0]-plot_boundary/2, init_vector[0]+plot_boundary/2))
+    elif input_dim==2:
+        ax = plt.figure().add_subplot(projection='3d')
+        plot_objective_2D(ax, fn, (init_vector[0]-plot_boundary/2, init_vector[0]+plot_boundary/2), (init_vector[1]-plot_boundary/2, init_vector[1]+plot_boundary/2))
+
+    optimiser = optimiser(list(x), **kwargs)
+
+    for _ in range(iters):
+        objective = fn(*x)
+
+        if input_dim==1:
+            plot_point_1D(ax, fn, x[0].item())
+        elif input_dim==2:
+            plot_point_2D(ax, fn, x[0].item(), x[1].item())
+
+        optimiser.zero_grad()
+        objective.backward()
+        optimiser.step()
+    
+    plt.ioff()
+    return tuple([x_i.item() for x_i in x])

optiviz-0.1.0/optiviz/visualise.py

@@ -0,0 +1,29 @@
+import torch
+import numpy as np
+import matplotlib.pyplot as plt
+
+def plot_objective_1D(ax, f, x_boundaries: tuple[float]) -> None:
+    x = np.linspace(*x_boundaries, 100)
+    z = f(torch.from_numpy(x).float()).detach().numpy()
+    ax.plot(x, z)
+
+def plot_point_1D(ax, f, x_highlight: float = None):
+    if x_highlight is not None:
+        z = f(torch.tensor([x_highlight])).item()
+        ax.set_title(f"({x_highlight:.4f}) -> {z:.4f}")
+        ax.scatter(x_highlight, z, marker='.', color='k', s=30)
+    plt.pause(0.05)
+
+def plot_objective_2D(ax, f, x_boundaries: tuple[int], y_boundaries: tuple[int]) -> None:
+    x = np.linspace(*x_boundaries, 100)
+    y = np.linspace(*y_boundaries, 100)
+    X, Y = np.meshgrid(x, y)
+    Z = f(torch.from_numpy(X).float(), torch.from_numpy(Y).float()).detach().numpy()
+    ax.plot_surface(X, Y, Z, cmap='plasma', alpha=0.3)
+
+def plot_point_2D(ax, f, x_highlight: float = None, y_highlight: float = None):
+    if x_highlight is not None and y_highlight is not None:
+        z = f(torch.tensor([x_highlight]), torch.tensor([y_highlight])).item()
+        ax.set_title(f"({x_highlight:.4f}, {y_highlight:.4f}) -> {z:.4f}")
+        ax.scatter(x_highlight, y_highlight, z, marker='.', color='k', s=30)
+    plt.pause(0.05)

optiviz-0.1.0/optiviz.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: optiviz
+Version: 0.1.0
+Summary: Educational tool for visualizing PyTorch-compatible optimisers on any differentiable 1D or 2D function.
+Author-email: Ronit Kunkolienker <ronitkunk@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Ronit Kunkolienker
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights  
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+        copies of the Software, and to permit persons to whom the Software is  
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all  
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE  
+        SOFTWARE.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: torch
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Dynamic: license-file
+
+# OptiViz
+OptiViz enables effortless visualisation of the optimisation sequence of *any* PyTorch optimiser on *any* differentiable function in one or two variables. OptiViz might find educational use in introductory nonlinear optimisation or deep learning classes.
+
+![Vanilla gradient descent minimising a convex quadratic form.](sgd.png "SGD")
+
+# Installation
+To install OptiViz, please use:
+```sh
+pip install optiviz
+```
+
+# Usage
+All functionality of OptiViz is exposed through the `optiviz.optimise` function.
+```python
+import torch
+from optiviz import optimise
+```
+Any optimisation problem has an objective function. OptiViz works with differentiable, real-valued objective functions in one or two variables.
+```math
+f : \mathbb{R} \rightarrow \mathbb{R}
+```
+```math
+g : \mathbb{R}^2 \rightarrow \mathbb{R}
+```
+In code, every input and output to the objective function must be a `torch.Tensor` of shape `(1,)`
+```python
+def f(x: torch.Tensor) -> torch.Tensor:
+    """
+    Example of an objective function in one variable.
+    """
+    return x ** 2
+def g(x: torch.Tensor, y: torch.Tensor) -> torch.Tensor:
+    """
+    Example of an objective function in two variables.
+    """
+    return x ** 2 + y ** 2 + x.sin() * y.sin()
+```
+The `optiviz.optimise` function (please see docstring) is used to visualise the optimisation sequence of the objective function using a PyTorch optimiser.
+```python
+arg_g_min = optimise(
+        g, # objective function
+        (12.5, 12.5), # initial values of the parameters being adjusted
+        plot_boundary=25,
+        iters=100,
+        optimiser=torch.optim.Adam, # PyTorch-compatible optimiser
+        lr=5e-1
+    )
+```

optiviz-0.1.0/optiviz.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE.txt
+README.md
+pyproject.toml
+optiviz/__init__.py
+optiviz/optimise.py
+optiviz/visualise.py
+optiviz.egg-info/PKG-INFO
+optiviz.egg-info/SOURCES.txt
+optiviz.egg-info/dependency_links.txt
+optiviz.egg-info/requires.txt
+optiviz.egg-info/top_level.txt
+tests/tests_1d.py
+tests/tests_2d.py
+tests/tests_ols.py

optiviz-0.1.0/optiviz.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

optiviz-0.1.0/optiviz.egg-info/requires.txt

@@ -0,0 +1,3 @@
+torch
+matplotlib
+numpy

optiviz-0.1.0/optiviz.egg-info/top_level.txt

@@ -0,0 +1 @@
+optiviz

optiviz-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "optiviz"
+version = "0.1.0"
+description = "Educational tool for visualizing PyTorch-compatible optimisers on any differentiable 1D or 2D function."
+authors = [{ name = "Ronit Kunkolienker", email = "ronitkunk@gmail.com" }]
+readme = "README.md"
+license = { file = "LICENSE.txt" }
+requires-python = ">=3.8"
+dependencies = [
+    "torch",
+    "matplotlib",
+    "numpy",
+]
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"

optiviz-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

optiviz-0.1.0/tests/tests_1d.py

@@ -0,0 +1,30 @@
+import torch
+from optiviz import optimise
+
+def f(x: torch.Tensor) -> torch.Tensor:
+    return x ** 2
+
+def g(x: torch.Tensor) -> torch.Tensor:
+    return x ** 2 + x.sin() ** 2
+
+def test_f_minimizer_1d():
+    arg_f_min = optimise(
+        f,
+        init_vector=(12.5,),
+        plot_boundary=25,
+        iters=100,
+        optimiser=torch.optim.SGD,
+        lr=1e-1
+    )
+    assert abs(arg_f_min[0]) < 0.05
+
+def test_g_minimizer_1d():
+    arg_g_min = optimise(
+        g,
+        init_vector=(12.5,),
+        plot_boundary=25,
+        iters=100,
+        optimiser=torch.optim.Adam,
+        lr=5e-1
+    )
+    assert abs(arg_g_min[0]) < 0.05

optiviz-0.1.0/tests/tests_2d.py

@@ -0,0 +1,30 @@
+import torch
+from optiviz import optimise
+
+def f(x: torch.Tensor, y: torch.Tensor) -> torch.Tensor:
+    return x ** 2 + y ** 2
+
+def g(x: torch.Tensor, y: torch.Tensor) -> torch.Tensor:
+    return x ** 2 + y ** 2 + x.sin() ** 2 + y.sin() ** 2
+
+def test_f_minimizer_2d():
+    arg_f_min = optimise(
+        f,
+        init_vector=(12.5, 12.5),
+        plot_boundary=25,
+        iters=100,
+        optimiser=torch.optim.SGD,
+        lr=1e-1
+    )
+    assert abs(arg_f_min[0]) < 0.05 and abs(arg_f_min[1]) < 0.05
+
+def test_g_minimizer_2d():
+    arg_g_min = optimise(
+        g,
+        init_vector=(12.5, 12.5),
+        plot_boundary=25,
+        iters=100,
+        optimiser=torch.optim.Adam,
+        lr=5e-1
+    )
+    assert abs(arg_g_min[0]) < 0.05 and abs(arg_g_min[1]) < 0.05

optiviz-0.1.0/tests/tests_ols.py

@@ -0,0 +1,20 @@
+import torch
+from optiviz import optimise
+
+X = [-2.0, -1.0, 0.0, 1.0, 2.0]
+Y = [2.0, 3.0, 4.0, 5.0, 6.0]
+
+def MSE(w: torch.Tensor, b: torch.Tensor, x=torch.tensor(X), y=torch.tensor(Y)):
+    errors = [((w * x[i] + b - y[i]) ** 2) for i in range(x.shape[0])]
+    return torch.stack(errors).mean(dim=0) / 2
+
+def test_ols_optimisation():
+    w_opt, b_opt = optimise(
+        MSE,
+        (12.5, 12.5),
+        plot_boundary=50,
+        iters=100,
+        optimiser=torch.optim.SGD,
+        lr=1e-1
+    )
+    assert abs(w_opt - 1) < 0.05 and abs(b_opt - 4) < 0.05