{"id":50459649,"url":"https://github.com/ripples-sci/ripples","last_synced_at":"2026-06-01T04:02:40.434Z","repository":{"id":361727556,"uuid":"1255584477","full_name":"ripples-sci/ripples","owner":"ripples-sci","description":"Ripples is a scientific computation library that aims to provide a unified, numerically accurate, with good performance and easy to use framework for multi-discipline numerical work. ","archived":false,"fork":false,"pushed_at":"2026-06-01T02:59:23.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T03:15:42.666Z","etag":null,"topics":["differentiation","optimization","python","ripples","scientific-computing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ripples-sci.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T01:45:32.000Z","updated_at":"2026-06-01T02:39:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ripples-sci/ripples","commit_stats":null,"previous_names":["ripples-sci/ripples"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ripples-sci/ripples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ripples-sci%2Fripples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ripples-sci%2Fripples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ripples-sci%2Fripples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ripples-sci%2Fripples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ripples-sci","download_url":"https://codeload.github.com/ripples-sci/ripples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ripples-sci%2Fripples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33759180,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["differentiation","optimization","python","ripples","scientific-computing"],"created_at":"2026-06-01T04:02:36.283Z","updated_at":"2026-06-01T04:02:40.409Z","avatar_url":"https://github.com/ripples-sci.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca id=\"top\"\u003e\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/ripples-sci/ripples_resources/main/graphical_resources/readme_upper_banner.svg\" alt=\"Banner failed to load.\" height=\"420px\"\u003e\n\n\u003ch2\u003e\n\u003c/h2\u003e\n\n\u003ch3\u003e\n  \u003ca href=\"https://github.com/ripples-sci/ripples/blob/main/CHANGELOG.md\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=VERSION\u0026secondaryLabel=0.1\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%231BD8D8\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"Version 0.1\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ripples-sci/ripples/blob/main/CHANGELOG.md\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=RELEASED\u0026secondaryLabel=June+2026\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%2315BFBF\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=1\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=none\u0026scale=1.15\u0026borderRadius=8\" alt=\"Released June 2026\"\u003e\u003c/a\u003e\n\u003c/h3\u003e\n\n\u003ch3\u003e\n  \u003ca href=\"#6---author\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=AUTHOR\u0026secondaryLabel=%C3%81lvaro+C%C3%A1tedra+S%C3%A1nchez\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%2310646A\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=1\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=none\u0026scale=1.15\u0026borderRadius=8\" alt=\"Author Álvaro Cátedra Sánchez\"\u003e\u003c/a\u003e\n\u003c/h3\u003e\n\n\u003ch3\u003e\n  \u003ca href=\"https://www.python.org/\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=PYTHON\u0026secondaryLabel=%E2%89%A5+3.10\u0026primaryBGColor=%233776AB\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%23FFD43B\u0026secondaryTextColor=%23000000\u0026primaryFontSize=12\u0026primaryFontWeight=600\u0026primaryLetterSpacing=2\u0026primaryFontFamily=Roboto\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026primaryIcon=python\u0026primaryIconColor=%23FFFFFF\u0026primaryIconSize=24\u0026primaryIconPosition=left\u0026scale=1.1\u0026borderRadius=5\" alt=\"Python \u003e= 3.10\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://numpy.org/\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=NUMPY\u0026secondaryLabel=%E2%89%A5+1.24\u0026primaryBGColor=%23013243\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%23FF6B35\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=12\u0026primaryFontWeight=600\u0026primaryLetterSpacing=2\u0026primaryFontFamily=Roboto\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026primaryIcon=numpy\u0026primaryIconColor=%23FFFFFF\u0026primaryIconSize=24\u0026primaryIconPosition=left\u0026scale=1.1\u0026borderRadius=5\" alt=\"NumPy \u003e= 1.24\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://apache.org/licenses/LICENSE-2.0\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=LICENSE\u0026secondaryLabel=APACHE+2.0\u0026primaryBGColor=%23D70015\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%238B0000\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=12\u0026primaryFontWeight=600\u0026primaryLetterSpacing=2\u0026primaryFontFamily=Roboto\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026primaryIcon=apache\u0026primaryIconColor=%23FFFFFF\u0026primaryIconSize=24\u0026primaryIconPosition=left\u0026scale=1.1\u0026borderRadius=5\" alt=\"License Apache 2.0\"\u003e\u003c/a\u003e\n\u003c/h3\u003e\n\n\u003cbr\u003e\n\n\u003c/div\u003e\n\n# Contents\n\n\u003ca href=\"#1---overview\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=1\u0026secondaryLabel=OVERVIEW\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%2319CFCF\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=7\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"01 - Overview\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003ca href=\"#2---installation\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=2\u0026secondaryLabel=INSTALLATION\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%2312B7B7\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"02 - Installation\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003ca href=\"#3---features\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=3\u0026secondaryLabel=FEATURES\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%23149999\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"03 - Features\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003ca href=\"#4---references\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=4\u0026secondaryLabel=REFERENCES\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%230E9B9B\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"04 - References\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003ca href=\"#5---roadmap\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=5\u0026secondaryLabel=ROADMAP\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%230F8084\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"05 - Roadmap\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003ca href=\"#6---author\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=6\u0026secondaryLabel=AUTHOR\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%2310646A\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"06 - Author\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003ca href=\"#7---contributing\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=7\u0026secondaryLabel=CONTRIBUTING\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%230B5960\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"07 - Contributing\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003ca href=\"#8---disclaimer\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=8\u0026secondaryLabel=DISCLAIMER\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%230A4E56\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"08 - Disclaimer\"\u003e\u003c/a\u003e\u003cbr\u003e\n\u003ca href=\"#9---license\"\u003e\u003cimg src=\"https://forthebadge.com/api/badges/generate?panels=2\u0026primaryLabel=9\u0026secondaryLabel=LICENSE\u0026primaryBGColor=%2316141F\u0026primaryTextColor=%23FFFFFF\u0026secondaryBGColor=%23073F46\u0026secondaryTextColor=%23FFFFFF\u0026primaryFontSize=11\u0026primaryFontWeight=800\u0026primaryLetterSpacing=3\u0026primaryFontFamily=Montserrat\u0026primaryTextTransform=uppercase\u0026secondaryFontSize=12\u0026secondaryFontWeight=900\u0026secondaryLetterSpacing=2\u0026secondaryFontFamily=Montserrat\u0026secondaryTextTransform=uppercase\u0026scale=1.15\u0026borderRadius=8\" alt=\"09 - License\"\u003e\u003c/a\u003e\n\n\n\u003cbr\u003e\u003c/br\u003e\n\n# 1 - Overview\n\n\u003cdiv style=\"text-align: justify\"\u003e\n\n## 1.1 - What is Ripples?\n\n**Ripples** is a scientific computation library built on top of NumPy that aims to \nprovide a unified, numerically accurate, with good performance and easy to use \nframework for multi-discipline numerical work.\n\nIt currently provides **differentiation** and **optimization** suites; many more \nsub-fields of computational science are planned for the future (see the \n[Roadmap](#5---roadmap)).\n\n## 1.2 - Why \"Ripples\"?\n\nAs someone who loves physics, the author is fascinated by the fact that much of modern \nphysics is fundamentally a ripple propagating through a field; from the light we see \nto gravity we experience.\n\nIn addition to this, the butterfly effect is equally fascinating. It perfectly \nrepresents the intrinsic chaotic nature of the many nonlinear differential equations \nthat govern so much of our world. This can be thought of as a ripple effect: tiny \nchanges at the start can lead to completely different outcomes, creating unpredictable \nchains of cause and effect.\n\nWith these two important and fundamental aspects of reality in mind, the chosen name \nfor a library intended to provide a framework to simulate and visualize said reality \nwas straightforward.\n\n## 1.3 - Philosophy\n\nThis library has been written with two kinds of people in mind.\n\n- **The user**, who just wants a library that simply works well. For this reason every \npublic function carries an extensive docstring: a description, brief usage guidelines, \nthe relevant references, and a worked examples block - enough to use it correctly, and \nenough to understand what it does.\n\n- **The reader**, who wants to understand how everything works, quickly and without \nfriction. Considerable effort has gone into the readability and the explanations of \nthe different files in this package, so that even a non-expert can follow what each \nfunction is doing. The documentation explains things thoroughly, but it is not a \ntextbook: anyone who wants to understand a method in full depth is pointed to the \nliterature, which is referenced throughout. The reading itself is guided, too - each \nsubmodule's `__init__.py` lists the recommended reading order, walking the code from \nthe lowest-level utilities up to the public entry point.\n\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n# 2 - Installation\n\n### Requirements\n\n- **Python** ≥ 3.10\n- **NumPy**  ≥ 1.24\n\n### Install via pip\n\n```bash\npip install ripples-sci\n```\n\n### Install from source\n\n```bash\ngit clone https://github.com/ripples-sci/ripples.git\ncd ripples\npip install -e .          # editable install\n```\n\n### Verify the installation\n\n```python\nimport ripples\nprint(ripples.__version__)\nripples.test()\n```\n\n\u003cbr\u003e\n\n# 3 - Features\n\nTwo suites - **differentiation** and **optimization** are available and can be reached \ndirectly from `import ripples`. The two sections below describe each suite: what it \ncovers, its public API, the object it returns, and a set of brief examples that show \nbasic functionalities.\n\n\n## 3.1 - Differentiation\n\n`ripples.differentiation` computes derivatives of scalar functions of any number of\nvariables: gradients, Hessians, and the full mixed-partial tensors of arbitrary order;\nthrough three numerical strategies of increasing accuracy and decreasing generality:\n\n| Strategy | Accuracy | Cost | Restrictions |\n|---|---|---|---|\n| **Central finite differences** | `O(h^(p+1-n))` | `p` evaluations per component | Function must be `n`-times continuously differentiable |\n| **Richardson extrapolation**   | Each pass adds `O(h^2)` more | `p + k` evaluations (`k` = number of passes) | Same as above, also gives a Romberg-style error bound |\n| **Complex-step method**        | ~machine precision (`O(eps)`) | **1** function evaluation | First derivatives only; function must be analytic over C |\n\n*`n` = derivative order, `p` = effective stencil point count, `h` = step size.*\n\n### Public API\n\n| Function | What it does |\n|---|---|\n| **`nth_numerical_derivative`** | Builds a callable that evaluates the n-th partial derivative of `f` (gradient, Hessian, or full mixed-partials tensor). |\n| **`numerical_hessian_vector_product`** | Computes `H(x) @ v` without ever forming the full Hessian - `O(p)` gradient calls regardless of dimension. |\n\n### Output\n\n**`DifferentiationResult`** - the object returned by both functions above. It is immutable and behaves like a read-only `numpy.ndarray` of the derivative, so it can be dropped straight into further array arithmetic while also carrying the full record of the computation:\n\n- `derivative` - the computed value (gradient vector, Hessian matrix, or full mixed-partials tensor).\n- `error_estimate` - a Romberg-style upper bound on the truncation error (available when Richardson extrapolation is used).\n- `differentiation_method` - which strategy produced the result (`'central_difference'`, `'richardson'`, or `'complex_step'`).\n- `is_scalar` - whether the input was a single-variable point.\n\ntogether with the rest of the configuration that produced it.\n\n### Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGradients, Hessians, and higher mixed partials\u003c/b\u003e\u003c/summary\u003e\n\n\n```python\nimport numpy as np\nfrom ripples import nth_numerical_derivative\n\n# Gradient of a 3-variable function\ndef f(x):\n    return x[0] ** 2 + 3.0 * x[1] + np.sin(x[2])\n\ngradient_f = nth_numerical_derivative(f, derivative_order=1)\nresult     = gradient_f(np.array([1.0, 2.0, 0.5]))\n\nresult.derivative                 # array([2., 3., 0.87758256])\nresult.differentiation_method     # 'central_difference'\n\n# Full Hessian via Richardson - bonus: a truncation error upper bound\ndef g(x):\n    return x[0] ** 2 * x[1] + x[1] ** 3\n\nhessian_g = nth_numerical_derivative(\n    g, derivative_order=2, richardson_extrapolation=True,\n)\nresult = hessian_g(np.array([1.0, 2.0]))\n\nresult.derivative                 # [[4., 2.], [2., 12.]]\nresult.error_estimate             # Romberg-style upper bound on the truncation error\n\n# Single component of a higher-order mixed partial\nmixed = nth_numerical_derivative(\n    g, derivative_order=3, single_component=(1, 1, 1),\n)\nmixed(np.array([1.0, 2.0])).derivative   # 6.0   (d^{3}g / dx_1^3)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHessian-vector products without forming the Hessian\u003c/b\u003e\u003c/summary\u003e\n\n\n```python\nfrom ripples import numerical_hessian_vector_product\n\nA = np.array([[4.0, 1.0], [1.0, 3.0]])\n\ndef grad_quadratic(x):\n    return A @ x\n\nhvp = numerical_hessian_vector_product(\n    gradient_function = grad_quadratic,\n    point             = np.array([1.0, -2.0]),\n    vector            = np.array([1.0,  1.0]),\n)\nhvp.derivative                    # array([5., 4.])  ==  A @ v\n```\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n## 3.2 - Optimization\n\n`ripples.optimization` exposes a single unified entry point - **`minimizer`** - that\ndispatches to ten algorithms covering first-order, line-search, trust-region, global,\nand constrained optimization. The same call shape works whether your problem is convex\nor non-convex, smooth or noisy, bounded or constrained, low- or moderate-dimensional.\n\nThe ten methods group into the following families:\n\n| Family | Methods (`method=`) | Best for |\n|---|---|---|\n| **First-order** | `nesterov`, `adam` | Noisy, stochastic, or piecewise-smooth objectives, or when starting close to an optimum. Poor as general-purpose solvers. |\n| **Conjugate gradient** | `conjugate_gradient` | Smooth problems with fewer than ~500 parameters. |\n| **Quasi-Newton** | `bfgs`, `lbfgs` | `bfgs` is best for smooth problems with \u003c ~500 parameters. `lbfgs` scales well for smooth problems with \u003e ~500 parameters and serves as an excellent general-purpose first try. |\n| **Newton-type** | `newton_conjugate_gradient` | Smooth, large-scale problems (\u003e ~500 parameters) where it scales efficiently. |\n| **Trust-region** | `trust_ncg`, `trust_lanczos` | Preferred for ill-conditioned or poorly scaled problems due to numerical stability. `trust_ncg` is also a great general-purpose first try and the default method; `trust_lanczos` is the least sensitive to ill-conditioning. Both suit smooth problems with \u003c ~500 parameters. |\n| **Global** | `direct`, `annealing` | `direct` is a brute-force grid search effective for tight boxes under ~4 dimensions. `annealing` is preferred for many local minima or bounded problems without a reliable gradient. |\n| **Constrained** | any of the above + `constraints=` / `bounds=` | General smooth constrained problems, via an Augmented-Lagrangian outer loop. |\n\n### Public API\n\n| Function | What it does |\n|---|---|\n| **`minimizer`** | The single unified entry point. Selects the algorithm through the `method` argument, builds numerical gradients and Hessian-vector products automatically when analytical ones are not supplied, and returns an `OptimizationResult`. |\n\n### Output\n\n**`OptimizationResult`** - every method returns this same object. It behaves like a read-only `numpy.ndarray` of the optimized parameters, so you can use it directly in further computation, while also recording everything about the run:\n\n- the outcome - `success`, `final_params`, `final_cost`, `termination_reason`;\n- the cost of getting there - `iteration_number`, `func_evals_number`, `grad_evals_number`, `elapsed_time`;\n- the shape of the problem - `is_bounded`, `is_constrained`, `constraint_count`, `is_global_method`;\n- and the full configuration that produced it.\n\nIt also offers conversion helpers (`as_array`, `as_float`, `to_list`, `to_dict`), equality checks (`==`, `allclose`), and a `summary(...)` method for a report. Printing the object shows a compact summary.\n\n### Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMinimize a smooth function with the default method\u003c/b\u003e\u003c/summary\u003e\n\n```python\nimport ripples\n\ndef rosenbrock(x):\n    return (1.0 - x[0]) ** 2 + 100.0 * (x[1] - x[0] ** 2) ** 2\n\nresult = ripples.minimizer(\n    function       = rosenbrock,\n    initial_params = [-1.2, 1.0],\n)\nresult.final_params      # ~ [1., 1.]\nresult.final_cost        # ~ 1e-18\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHessian-vector product for trust-region in moderate dimension\u003c/b\u003e\u003c/summary\u003e\n\n```python\nrng = np.random.default_rng(seed=0)\nA   = rng.standard_normal((5, 5))\nA   = A @ A.T + np.eye(5)                # Symmetric Positive Definite\n\ndef f(x):     return 0.5 * x @ A @ x\ndef g(x):     return A @ x\ndef hvp(x,p): return A @ p               # constant Hessian\n\nresult = minimizer(\n    function                = f,\n    initial_params          = rng.standard_normal(5),\n    method                  = 'trust_lanczos',\n    gradient_function       = g,\n    hessian_vector_function = hvp,\n)\nresult.final_params                      # ~ [0, 0, 0, 0, 0]\nresult.final_cost                        # ~ 0.\nresult.hessian_vector_product_provided   # True\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBox bounds - optimum on the boundary\u003c/b\u003e\u003c/summary\u003e\n\n```python\ndef shifted_sphere(x):\n    return np.sum((x - 3.0) ** 2)        # unconstrained min at [3, 3]\n\nresult = minimizer(\n    function       = shifted_sphere,\n    initial_params = [0.0, 0.0],\n    method         = 'lbfgs',\n    bounds         = ([-1.0, -1.0], [1.0, 1.0]),\n)\nresult.final_params    # ~ [1., 1.]      (corner of the box)\nresult.is_bounded      # True\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eEquality constraint\u003c/b\u003e\u003c/summary\u003e\n\n```python\ndef objective(x): return (x[0] - 3.0) ** 2 + (x[1] - 2.0) ** 2\nconstraints = (\n    {'type': 'eq', 'fun': lambda x: x[0] + x[1] - 3.0},\n)\n\nresult = minimizer(\n    function       = objective,\n    initial_params = [0.0, 0.0],\n    method         = 'bfgs',\n    constraints    = constraints,\n)\nresult.final_params      # ~ [2., 1.]       (unconstrained solution is at [3., 2.])\nresult.constraint_count  # ~ 1\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGlobal optimization on Rastrigin\u003c/b\u003e\u003c/summary\u003e\n\n```python\ndef rastrigin(x):\n    return 10.0 * len(x) + np.sum(x ** 2 - 10.0 * np.cos(2.0 * np.pi * x))\n\nresult = minimizer(\n    function      = rastrigin,\n    method        = 'annealing',\n    bounds        = ([-512., -512.], [512., 512.]),\n    method_params = {'f_min': 1e-13},\n)\nresult.is_global_method   # True\nresult.final_params       # ~ [0., 0.]\n```\n\u003c/details\u003e\n\n\n\n\u003cbr\u003e\n\n# 4 - References\n\nEvery entry below is a source actually cited in the docstrings of the submodule\nfiles. Each one notes the methods that rely on it.\n\n## 4.1 - Differentiation\n\n1. **Press, W. H., Teukolsky, S. A., Vetterling, W. T., \u0026 Flannery, B. P. (2007).** *Numerical Recipes: The Art of Scientific Computing* (3rd ed.), §5.7. Cambridge University Press. ISBN 978-0-521-88068-8. - Central-difference stencils and the Romberg-style truncation error estimate.\n\n2. **LeVeque, R. J. (2007).** *Finite Difference Methods for Ordinary and Partial Differential Equations: Steady-State and Time-Dependent Problems*, §1. SIAM. [https://doi.org/10.1137/1.9780898717839](https://doi.org/10.1137/1.9780898717839) - Finite-difference foundations and the Hessian-vector product.\n\n3. **Martins, J. R. R. A., Sturdza, P., \u0026 Alonso, J. J. (2003).** *The complex-step derivative approximation.* ACM Transactions on Mathematical Software, 29(3), 245–262. [https://doi.org/10.1145/838250.838251](https://doi.org/10.1145/838250.838251) - The complex-step method.\n\n4. **Burden, R. L., Faires, J. D., \u0026 Burden, A. M. (2016).** *Numerical Analysis* (10th ed.), §§4.2 \u0026 4.5. Cengage Learning. ISBN 978-1-305-25366-7. - Richardson extrapolation and the automatic step-size selection.\n\n5. **Wikipedia contributors.** *Finite differences.* [https://en.wikipedia.org/wiki/Finite_difference#Multivariate_finite_differences](https://en.wikipedia.org/wiki/Finite_difference#Multivariate_finite_differences) - Multivariate (mixed-partial) finite-difference composition.\n\n## 4.2 - Optimization\n\n1. **Nocedal, J., \u0026 Wright, S. J. (2006).** *Numerical Optimization* (2nd ed.). Springer Series in Operations Research and Financial Engineering. Springer, New York. [https://doi.org/10.1007/978-0-387-40065-5](https://doi.org/10.1007/978-0-387-40065-5) - Conjugate gradient (§5.4, eq. 5.45), BFGS (§6.1, eqs. 6.19–6.20), Newton-CG (§7.1), L-BFGS (§7.4–7.5), trust-region NCG (§7.2), trust-region Lanczos (pp. 175–176, Theorem 4.1, §4.3), and the augmented-Lagrangian outer loop (§17.3–17.4).\n\n2. **Kochenderfer, M. J., \u0026 Wheeler, T. A. (2019).** *Algorithms for Optimization.* MIT Press. ISBN 978-0-262-03942-0. - Nesterov accelerated gradient (§5.4), Adam (§5.8), DIRECT (§7.6), and dual annealing (§8.3).\n\n3. **SciPy contributors (2026).** *SciPy.optimize._linesearch.py source code (Version 1.17.1).* GitHub. [Source](https://github.com/scipy/scipy/blob/bb6b9da396f15355efdb2e28bdfa1aead105ce92/scipy/optimize/_linesearch.py) - Wolfe line search.\n\n4. **Wikipedia contributors.** *Conjugate gradient method.* [https://en.wikipedia.org/wiki/Conjugate_gradient_method](https://en.wikipedia.org/wiki/Conjugate_gradient_method) - Linear conjugate gradient background.\n\n5. **Wikipedia contributors.** *Nonlinear conjugate gradient method.* [https://en.wikipedia.org/wiki/Nonlinear_conjugate_gradient_method](https://en.wikipedia.org/wiki/Nonlinear_conjugate_gradient_method) - Polak-Ribière+ nonlinear conjugate gradient.\n\n6. **Wikipedia contributors.** *BFGS method.* [https://en.wikipedia.org/wiki/BFGS](https://en.wikipedia.org/wiki/BFGS) - The BFGS Hessian update.\n\n7. **Wikipedia contributors.** *Limited-memory BFGS (L-BFGS).* [https://en.wikipedia.org/wiki/LBFGS](https://en.wikipedia.org/wiki/LBFGS) - The L-BFGS two-loop recursion.\n\n8. **Gould, N. I. M., Lucidi, S., Roma, M., \u0026 Toint, P. L. (1999).** *Solving the trust-region subproblem using the Lanczos method.* SIAM Journal on Optimization, 9(2), 504–525. [https://doi.org/10.1137/S1052623497322735](https://doi.org/10.1137/S1052623497322735) - The GLTR / Lanczos trust-region subproblem solver.\n\n9. **Tsallis, C., \u0026 Stariolo, D. A. (1996).** *Generalized simulated annealing.* Physica A, 233(1–2), 395–406. [https://doi.org/10.1016/S0378-4371(96)00271-3](https://doi.org/10.1016/S0378-4371(96)00271-3) - Generalized simulated annealing.\n\n10. **Xiang, Y., Gubian, S., \u0026 Martin, F. (2017).** *Generalized Simulated Annealing.* In *Computational Optimization in Engineering - Paradigms and Applications.* [http://dx.doi.org/10.5772/66071](http://dx.doi.org/10.5772/66071) - Dual annealing with periodic local refinement.\n\n11. **Wikipedia contributors.** *q-Gaussian distribution.* [https://en.wikipedia.org/wiki/Q-Gaussian_distribution#Related_distributions](https://en.wikipedia.org/wiki/Q-Gaussian_distribution#Related_distributions) - The q-Gaussian visiting distribution used by dual annealing.\n\n\u003cbr\u003e\n\n# 5 - Roadmap\n\n| Version | Status | Scope / Module | Objective to implement |\n| :--- | :--- | :--- | :--- |\n| **0.1.X** | In progress | Bug fixes and readability improvements | Resolve open issues and improve clarity of the v0.1 codebase. |\n| **0.X.0** | Planned | `ripples.optimization` | Implement multiple 1-dimensional methods, expand global methods, and improve the performance of existing algorithms. |\n| **0.X.0** | Planned | `ripples.differentiation` | Introduce numerical alternatives including the Fornberg method and multi-complex step differentiation to expand current complex-step capabilities. |\n| **0.X.0** | Planned | `ripples.integration` | Implement quadrature rules and ODE/PDE solvers. |\n| **0.X.0** | Planned | `ripples.root_finding` | Provide multi-dimensional root-finding routines. |\n| **0.X.0** | Planned | `ripples.interpolation` | Integrate standard interpolation routines for data smoothing and continuous approximation. |\n| **0.X.0** | Planned | `ripples.differentiation` | Add Automatic Differentiation for both forward-mode and reverse-mode execution. |\n| **0.X.0** | Planned | `ripples.machine_learning` | Provide a comprehensive suite of classical machine learning models for both supervised and unsupervised learning. |\n| **0.X.0** | Planned | `ripples.machine_learning` | Design and build a modular neural network module. |\n| **0.X.0** | Planned | `ripples.control_theory` | The foundations of control theory: state-space representation, transfer functions, PID controllers, and optimal control structures. |\n| **0.X.0** | Planned | `ripples.simulation` | Build a core simulation API for Computational Fluid Dynamics (CFD) and Finite Element Method (FEM). |\n| **0.X.0** | Planned | `ripples.visualization` | Provide convenience plotting helpers for most native data types, training results, and simulation curves. |\n| **0.X.0** | Planned | Performance Redesign | Introduce compiled loops, multithreading, and parallelized computation while remaining an accessible, user-friendly package. |\n| **1.0.0** | Goal | Production Release | Deliver a complete numerical computation and engineering library providing robust routines for most scientific disciplines, backed by a stable public API. |\n\nNotes:\n- The 0.X.0 versions are not presented in chronological order and are subject to change.\n- There is no expected release timeline for the planned pre-realease versions, given \nthe project's ambitious roadmap, full implementation is expected to be a multi-year \neffort.\n\n\n\u003cbr\u003e\n\n# 6 - Author\n\n**Álvaro Cátedra Sánchez**, last year Aerospace Engineering student with great \ninterest in scientific computing; unique author, maintainer, and responsible for \noverall design, numerical methods implementation, and API consistency.\n\nProfessional contact:\n[`alvaro.catedra.sanchez@gmail.com`](mailto:alvaro.catedra.sanchez@gmail.com)\n\n\u003cbr\u003e\n\n# 7 - Contributing\n\nAlthough this library was created by a single author in order to gain a deep learning\nabout the extensive field that is scientific computation; ***any*** feedback, bug\nreports, or suggestions that could improve the library or its author in any way will\nbe ***greatly*** appreciated.\n\n\u003cbr\u003e\n\n# 8 - Disclaimer\n\nRipples is pre-release software (versions before `1.0`). The public API is **stable\nwithin a minor version** but may evolve between minor versions until `1.0`. While\nconsiderable care has been taken to make the numerical methods accurate and\nwell-conditioned, no guarantee is given that any particular result is fit for any\nparticular purpose; the user is responsible for validating results against their own\nproblem requirements.\n\n\u003cbr\u003e\n\n# 9 - License\n\nRipples is distributed under the **Apache License, Version 2.0**.\n\nYou may use, modify, and distribute this software under the terms of the license,\nprovided that proper attribution to the original author is preserved in all copies\nor substantial portions of the software. See [`LICENSE.txt`](LICENSE.txt) at the\nrepository root for the full text.\n\n```\nCopyright (c) Álvaro Cátedra Sánchez\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n```\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/ripples-sci/ripples_resources/main/graphical_resources/readme_lower_banner.png\" alt=\"Banner failed to load.\" height=\"420px\"\u003e\n\n\u003ca href=\"#top\"\u003e⬆ Back to top\u003c/a\u003e\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fripples-sci%2Fripples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fripples-sci%2Fripples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fripples-sci%2Fripples/lists"}