{"id":15057602,"url":"https://github.com/jinraekim/parametrisedconvexapproximators.jl","last_synced_at":"2025-04-10T11:10:38.068Z","repository":{"id":42351808,"uuid":"404649029","full_name":"JinraeKim/ParametrisedConvexApproximators.jl","owner":"JinraeKim","description":"A Julia package for parameterized convex approximators including parameterized log-sum-exp (PLSE) network.","archived":false,"fork":false,"pushed_at":"2025-03-31T14:50:28.000Z","size":29719,"stargazers_count":9,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-31T16:04:14.196Z","etag":null,"topics":["deep-learning","julia","machine-learning"],"latest_commit_sha":null,"homepage":"","language":"Julia","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/JinraeKim.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":"2021-09-09T08:44:49.000Z","updated_at":"2025-01-24T23:00:28.000Z","dependencies_parsed_at":"2023-11-15T07:25:48.131Z","dependency_job_id":"60978268-7afc-4ed9-96b2-1e2f9d439ebc","html_url":"https://github.com/JinraeKim/ParametrisedConvexApproximators.jl","commit_stats":{"total_commits":71,"total_committers":1,"mean_commits":71.0,"dds":0.0,"last_synced_commit":"0ab88960f6ac5afd01bf0008f223045462af8e56"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JinraeKim%2FParametrisedConvexApproximators.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JinraeKim%2FParametrisedConvexApproximators.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JinraeKim%2FParametrisedConvexApproximators.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JinraeKim%2FParametrisedConvexApproximators.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JinraeKim","download_url":"https://codeload.github.com/JinraeKim/ParametrisedConvexApproximators.jl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248208560,"owners_count":21065202,"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":["deep-learning","julia","machine-learning"],"created_at":"2024-09-24T22:09:02.307Z","updated_at":"2025-04-10T11:10:38.046Z","avatar_url":"https://github.com/JinraeKim.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ParametrisedConvexApproximators\n[ParametrisedConvexApproximators.jl](https://github.com/JinraeKim/ParametrisedConvexApproximators.jl)\nis a Julia package providing predefined parametrised convex approximators and related functionalities.\nAn official package of [^3].\n\n\n## Installation\nTo install ParametrisedConvexApproximator,\nplease open Julia's interactive session (a.k.a REPL) and press `]` key\nin the REPL to use the package mode, then type the following command\n\n```julia\npkg\u003e add ParametrisedConvexApproximator\n```\n\n### Notes\n- For PLSE(plus), the differentiation of the minimiser is now available via implicit differentiation.\n- The benchmark result was reported in [ParametrisedConvexApproximator.jl v0.1.1](https://github.com/JinraeKim/ParametrisedConvexApproximators.jl/tree/v0.1.1) [^3].\n\n\n## Quick Start\nParametrisedConvexApproximators.jl focuses on providing predefined approximators\nincluding parameterized convex approximators.\nNote that when approximators receive two arguments, the first and second arguments correspond to\nparameter and optimization variable, usually denoted by `x` and `u`, respectively.\n\nNote that the terms of parameter `x` and optimization variable `u` are often referred to as condition and decision from the decision-making point of view [^3].\n\nApplications include amortized optimization (learning-based parametric optimization) [^5].\n\n### Network construction\n```julia\nusing ParametrisedConvexApproximators\nusing Flux\nusing Random  # to reproduce the following result\n\n# construction\nseed = 2023\nRandom.seed!(seed)\nn, m = 3, 2\ni_max = 20\nT = 1.0\nh_array = [64, 64]\nact = Flux.leakyrelu\nnetwork = PLSE(n, m, i_max, T, h_array, act)  # parametrised log-sum-exp (PLSE) network\nx, u = rand(n), rand(m)\nf̂ = network(x, u)\n@show f̂\n```\n\n```julia\nf̂ = [3.029994811790289]\n```\n\n### Prepare dataset\n```julia\nmin_condition = -ones(n)\nmax_condition = +ones(n)\nmin_decision = -ones(m)\nmax_decision = +ones(m)\ntarget_function_name = :quadratic\ntarget_function = example_target_function(target_function_name)  # f(x, u) = x'*x + u'*u\nN = 5_000\n\ndataset = DecisionMakingDataset(\n    target_function;\n    target_function_name=:quadratic,  # just for metadata\n    N=N, n=n, m=m, seed=seed,\n    min_condition=min_condition,\n    max_condition=max_condition,\n    min_decision=min_decision,\n    max_decision=max_decision,\n)\n```\n\n### Network training\n```julia\ntrainer = SupervisedLearningTrainer(dataset, network; optimiser=Adam(1e-4))\n\n@show get_loss(trainer.network, trainer.dataset[:train], trainer.loss)\n@show get_loss(trainer.network, trainer.dataset[:validate], trainer.loss)\nbest_network = Flux.train!(trainer; epochs=200)\n@show get_loss(best_network, trainer.dataset[:test], trainer.loss)\n```\n\n```julia\n\n...\n\nepoch: 199/200\nloss_train = 0.0001664964550015733\nloss_validate = 0.0003002414225961646\nBest network found!\nminimum_loss_validate = 0.0003002414225961646\nepoch: 200/200\nloss_train = 0.0001647995673689787\nloss_validate = 0.00029825480495257375\nBest network found!\nminimum_loss_validate = 0.00029825480495257375\n\n```\n\n### Find a minimizer `u` for given parameter `x`\n```julia\n# optimization\nRandom.seed!(seed)\nx = rand(n)  # any value\nminimiser = minimise(network, x; u_min=min_decision, u_max=max_decision)  # box-constrained minimization; you can define your own optimization problem manually.\n@show minimiser\n@show network(x, minimiser)\n@show dataset[:train].metadata.target_function(x, minimiser)\n```\n\n```julia\nminimiser = [-0.003060366520019827, 0.007150205329478883]\nnetwork(x, minimiser) = [0.9629849722035002]\n(dataset[:train]).metadata.target_function(x, minimiser) = 0.9666740244969058\n```\n\n\n\n## Documentation\n### Types\n- `AbstractApproximator` is an abstract type of approximator.\n- `ParametrisedConvexApproximator \u003c: AbstractApproximator` is an abstract type of parametrised convex approximator.\n- `ConvexApproximator \u003c: ParametrisedConvexApproximator` is an abstract type of convex approximator.\n- `DifferenceOfConvexApproximator \u003c: AbstractApproximator` is an abstract type of difference of convex approximator.\n\n### Approximators\n- All approximators in ParametrisedConvexApproximators.jl receive two arguments, namely, `x` and `u`.\nWhen `x` and `u` are vectors whose lengths are `n` and `m`, respectively,\nthe output of an approximator is **one-length vector**.\n    - Note that `x` and `u` can be matrices, whose sizes are `(n, d)` and `(m, d)`,\n    for evaluations of `d` pairs of `x`'s and `u`'s.\n    In this case, the output's size is `(1, d)`.\n\n- The list of predefined approximators:\n    - `FNN::AbstractApproximator`: feedforward neural network\n    - `MA::ConvexApproximator`: max-affine (MA) network [^1]\n    - `LSE::ConvexApproximator`: log-sum-exp (LSE) network [^1]\n    - `PICNN::ParametrisedConvexApproximator`: partially input-convex neural network (PICNN) [^2]\n    - `PMA::ParametrisedConvexApproximator`: parametrised MA (PMA) network [^3]\n    - `PLSE::ParametrisedConvexApproximator`: parametrised LSE (PLSE) network [^3]\n        - The default setting is `strict = false`.\n        - `PLSEPlus` = `PLSE` with `strict=true`\n    - `DLSE::DifferenceOfConvexApproximator`: difference of LSE (DLSE) network [^4]\n\n### Interface\n- `(nn::approximator)(x, u)` provides the approximate function value.\n- `minimiser = minimise(approximator, x; u_min=nothing, u_max=nothing)` provides the minimiser for given parameter `x`\nconsidering box constraints of `u \u003e= u_min` and `u \u003c= u_max` (element-wise).\n    - The parameter `x` can be a vector, i.e., `size(x) = (n,)`,\n    or a matrix for multiple parameters via multi-threading, i.e., `size(x) = (n, d)`.\n\n### Dataset\n- `DecisionMakingDataset`\n\n### Trainer\n- `SupervisedLearningTrainer`\n\n\n## Gallery\n### PMA and PLSE networks illustration\nSee `./examples/visualization.jl`.\n\n\n#### MA network construction in theory\n- The following illustration shows the construction of MA network for given convex function.\n- See [^1].\n- **NOTICE**: the following illustration does not show the training progress.\n\n\u003cimg src=./anim_ma.gif width=50% height=50%\u003e\n\n#### PMA network construction in theory\n- The following illustration shows the construction of PMA network for given parameterized convex function.\n- See [^3], Theorem 3.\n- **NOTICE**: the following illustration does not show the training progress.\n\n\u003cimg src=./anim_pma.gif width=50% height=50%\u003e\n\n#### PLSE construction in theory\n- The following illustration shows the PLSE network with different temperature for the corresponding PMA network constructed above.\n- See [^3], Corollary 1.\n\n\u003cimg src=./anim_plse.gif width=50% height=50%\u003e\n\n\n### Comparison between MA and PMA networks\n#### Subgradient selection in MA network\n- To construct an MA network[^1],\nany subgradient can arbitrarily be selected.\n\n\u003cimg src=./anim_ma_subgrad.gif width=50% height=50%\u003e\n\n#### Subgradient function selection in PMA network\n- To construct an PMA network[^1],\nthe subgradient function, a function of parameter `x`,\nshould carefully be considered so that it can be continuous and represent (approximate)\nthe subgradient function well.\n    - As shown in the following, the subgradient function may be multivalued.\n\n\u003cimg src=./anim_pma_subgrad.gif width=50% height=50%\u003e\n\nThe subgradient function can be approximated by a continuous approximate selection.\n\n##### Notion of continuous approximate selection\n- Given multivalued function $f:X \\to Y$,\na single-valued function $g: X \\to Y$ is said to be a *continuous approximate selection*\nif $\\textup{Graph}(g) \\subset \\textup{Graph}(B(f, \\epsilon))$.\n    - The following figure adopts $L_{1}$-norm for illustration.\n\u003cimg src=./continuous_approximate_selection.png width=50% height=50%\u003e\n\n\n## References\n[^1]: [G. C. Calafiore, S. Gaubert, and C. Possieri, “Log-Sum-Exp Neural Networks and Posynomial Models for Convex and Log-Log-Convex Data,” IEEE Transactions on Neural Networks and Learning Systems, vol. 31, no. 3, pp. 827–838, Mar. 2020, doi: 10.1109/TNNLS.2019.2910417.](https://ieeexplore.ieee.org/abstract/document/8715799?casa_token=ptHxee1NJ30AAAAA:etAIY0UkR0yg6YK7mgtEzCzHavM0d6Cos1VNzpn0cw5hbiEnFnAxNDm1rflWjDAOa-iO6xU5Lg)\n[^2]: [B. Amos, L. Xu, and J. Z. Kolter, “Input Convex Neural Networks,” in Proceedings of the 34th International Conference on Machine Learning, Sydney, Australia, Jul. 2017, pp. 146–155.](http://proceedings.mlr.press/v70/amos17b.html)\n[^3]: [J. Kim and Y. Kim, “Parameterized Convex Universal Approximators for Decision-Making Problems,” IEEE Trans. Neural Netw. Learning Syst., accepted for publication, 2022, doi: 10.1109/TNNLS.2022.3190198.](https://ieeexplore.ieee.org/document/9833537)\n[^4]: [G. C. Calafiore, S. Gaubert, and C. Possieri, “A Universal Approximation Result for Difference of Log-Sum-Exp Neural Networks,” IEEE Transactions on Neural Networks and Learning Systems, vol. 31, no. 12, pp. 5603–5612, Dec. 2020, doi: 10.1109/TNNLS.2020.2975051.](https://ieeexplore.ieee.org/abstract/document/9032340)\n[^5]: [J. Kim and Y. Kim, “Parameterized Convex Minorant for Objective Function Approximation in Amortized Optimization.” arXiv, Oct. 03, 2023. arXiv:2310.02519 (submitted to Journal of Machine Learning Research)](https://arxiv.org/abs/2310.02519)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjinraekim%2Fparametrisedconvexapproximators.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjinraekim%2Fparametrisedconvexapproximators.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjinraekim%2Fparametrisedconvexapproximators.jl/lists"}