{"id":43292660,"url":"https://github.com/arunoruto/lumafit","last_synced_at":"2026-02-01T18:34:57.678Z","repository":{"id":294338306,"uuid":"986623015","full_name":"arunoruto/lumafit","owner":"arunoruto","description":"A Numba-accelerated Levenberg-Marquardt fitting library","archived":false,"fork":false,"pushed_at":"2026-01-25T01:40:13.000Z","size":302,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-25T14:53:33.177Z","etag":null,"topics":["fitting","least-","levenberg-marquardt","numba","optimization","scientific"],"latest_commit_sha":null,"homepage":"https://arunoruto.github.io/lumafit/","language":"Python","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/arunoruto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-19T22:20:31.000Z","updated_at":"2026-01-25T01:40:17.000Z","dependencies_parsed_at":"2025-06-22T02:25:42.421Z","dependency_job_id":"ab60de8a-d5ab-4938-b1c6-1cbad65f0dbf","html_url":"https://github.com/arunoruto/lumafit","commit_stats":null,"previous_names":["arunoruto/lmba","arunoruto/lumafit"],"tags_count":5,"template":false,"template_full_name":"arunoruto/python.nix","purl":"pkg:github/arunoruto/lumafit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arunoruto%2Flumafit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arunoruto%2Flumafit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arunoruto%2Flumafit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arunoruto%2Flumafit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arunoruto","download_url":"https://codeload.github.com/arunoruto/lumafit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arunoruto%2Flumafit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28985818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T18:17:03.387Z","status":"ssl_error","status_checked_at":"2026-02-01T18:16:57.287Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["fitting","least-","levenberg-marquardt","numba","optimization","scientific"],"created_at":"2026-02-01T18:34:57.606Z","updated_at":"2026-02-01T18:34:57.664Z","avatar_url":"https://github.com/arunoruto.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 --\u003e\n\n\u003ca id=\"readme-top\"\u003e\u003c/a\u003e\n\n\u003c!-- PROJECT SHIELDS --\u003e\n\u003c!-- Add shields relevant to your project, e.g., build status, PyPI version --\u003e\n\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![License][license-shield]][license-url]\n\n\u003c!-- Optional: [![LinkedIn][linkedin-shield]][linkedin-url] --\u003e\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003c!-- Replace with your project logo if you have one --\u003e\n  \u003c!-- \u003ca href=\"https://github.com/arunoruto/lumafit]\"\u003e\u003cimg src=\"images/logo.png\" alt=\"Logo\" width=\"80\" height=\"80\"\u003e\u003c/a\u003e --\u003e\n\n  \u003ch3 align=\"center\"\u003elumafit\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    A Numba-accelerated Levenberg-Marquardt fitting library for Python.\n    \u003cbr /\u003e\n    Optimized for pixel-wise fitting on 3D image data.\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003c!-- Optional: Add links to documentation if you create it later --\u003e\n    \u003c!-- \u003ca href=\"https://github.com/arunoruto/lumafit]\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e --\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/arunoruto/lumafit/issues/new?labels=bug\u0026template=bug-report---.md\"\u003eReport Bug\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/arunoruto/lumafit/issues/new?labels=enhancement\u0026template=feature-request---.md\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#built-with\"\u003eBuilt With\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#tests\"\u003eTests\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#acknowledgments\"\u003eAcknowledgments\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n\n## About The Project\n\nThis library provides a high-performance implementation of the Levenberg-Marquardt (LM) algorithm for non-linear least squares fitting, accelerated using [Numba](https://numba.pydata.org/).\n\nThe primary motivation for `lumafit` is to efficiently perform fitting tasks on large multi-dimensional datasets, such as fitting a curve along the third dimension for every pixel in a 3D image stack. Numba's Just-In-Time (JIT) compilation and parallel processing capabilities (`numba.prange`) are leveraged to drastically reduce computation time compared to pure Python implementations.\n\nKey features:\n\n- Core Levenberg-Marquardt algorithm (`levenberg_marquardt_core`).\n- Specialized function for fitting curves pixel-wise on 3D data (`levenberg_marquardt_pixelwise`) with parallel execution.\n- Support for weighted least squares.\n- Numerical Jacobian calculation via finite differences (Numba-accelerated).\n- Implementation based on standard LM algorithm formulations.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n### Built With\n\n- [![Python][Python.any]][Python-url]\n- [![Numba][Numba-shield]][Numba-url]\n- [![NumPy][NumPy-shield]][NumPy-url]\n- [![SciPy][SciPy-shield]][SciPy-url] (Used in tests for comparison)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- GETTING STARTED --\u003e\n\n## Getting Started\n\nTo get a local copy of `lumafit` up and running, follow these simple steps.\n\n### Prerequisites\n\nYou need Python 3.9+ installed. Using a virtual environment is recommended.\nYou will also need standard Python build tools, typically included with `pip`.\n\n```sh\npython -m venv venv\nsource venv/bin/activate # On Linux/macOS\n# venv\\Scripts\\activate # On Windows\n```\n\n### Installation\n\n1. Clone the repository:\n   ```sh\n   git clone https://github.com/arunoruto/lumafit.git\n   cd lumafit\n   ```\n2. Install the package using `pip`, which will use the `pyproject.toml` file:\n   ```sh\n   pip install .\n   ```\n   If you want to install dependencies required for running tests, use the `[test]` extra:\n   ```sh\n   pip install .[test]\n   ```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- USAGE EXAMPLES --\u003e\n\n## Usage\n\nThe library provides two main functions: `levenberg_marquardt_core` for fitting a single curve and `levenberg_marquardt_pixelwise` for fitting a 3D data stack.\n\nFirst, you need to define your model function. **Your model function must be compatible with Numba's `nopython=True` mode.** This means it should primarily use NumPy functions and basic Python constructs supported by Numba.\n\n```python\n# Example model function (exponential decay + another exponential decay)\nimport numpy as np\nfrom numba import jit\n\n@jit(nopython=True, cache=True)\ndef my_model(t, p):\n    \"\"\"\n    My example non-linear model.\n\n    Args:\n        t (np.ndarray): Independent variable (1D array).\n        p (np.ndarray): Parameters (1D array), e.g., [A1, tau1, A2, tau2].\n\n    Returns:\n        np.ndarray: Model output evaluated at t.\n    \"\"\"\n    # Add checks for potential zero divisors if parameters are in denominators\n    term1 = np.zeros_like(t, dtype=np.float64)\n    if np.abs(p[1]) \u003e 1e-12: # Avoid division by zero or near-zero\n        term1 = p[0] * np.exp(-t / p[1])\n\n    term2 = np.zeros_like(t, dtype=np.float64)\n    if np.abs(p[3]) \u003e 1e-12:\n         term2 = p[2] * np.exp(-t / p[3])\n\n    return term1 + term2\n\n# Or the polarization model:\n# @jit(nopython=True, cache=True)\n# def polarization_model(t, p):\n#     # ... (your polarization model code from tests/lmba.py)\n#     t_rad = t * np.pi / 180.0\n#     p3_rad = p[3] * np.pi / 180.0\n#     sin_t_rad_arr = np.sin(t_rad)\n#     term1_base = sin_t_rad_arr.copy()\n#     mask_problematic_base = (np.abs(term1_base) \u003c 1e-15) \u0026 (p[1] \u003c 0.0) # Using a small epsilon\n#     term1_base[mask_problematic_base] = 1e-15 # Replace near-zero with tiny number\n#     term1 = np.power(term1_base, p[1])\n#     term2 = np.power(np.cos(t_rad / 2.0), p[2])\n#     term3 = np.sin(t_rad - p3_rad)\n#     return p[0] * term1 * term2 * term3\n```\n\n### Fitting a single curve\n\nIf you have a single 1D array of data (`y_data`) corresponding to independent variable values (`t_data`), you can use `levenberg_marquardt_core`. This function is the core engine for minimizing the difference between your model and the data.\n\n```python\nimport numpy as np\nfrom lmba import levenberg_marquardt_core\n\n# Assume my_model is defined and JIT-compiled above\n\n# Generate some synthetic data (replace with your actual data)\nt_data = np.linspace(0.1, 25, 100, dtype=np.float64)\np_true = np.array([5.0, 2.0, 2.0, 10.0], dtype=np.float64)\ny_clean = my_model(t_data, p_true)\nnoise = np.random.default_rng(42).normal(0, 0.1, size=t_data.shape).astype(np.float64)\ny_data = (y_clean + noise).astype(np.float64)\n\n# Initial guess for parameters\np_initial = np.array([4.0, 1.5, 1.5, 8.0], dtype=np.float64)\n\n# Optional: weights (e.g., inverse variance if noise std is known)\nweights = 1.0 / (0.1**2 + np.finfo(float).eps) # Assuming noise_std = 0.1\n\n# Run the fit\np_fit, cov, chi2, iters, conv = levenberg_marquardt_core(\n    my_model,       # Your Numba-compiled model function\n    t_data,         # Independent variable data (1D array)\n    y_data,         # Dependent variable data (1D array)\n    p_initial,      # Initial guess (1D array)\n    weights=weights, # Optional weights (1D array or None)\n    max_iter=1000,  # Max iterations\n    tol_g=1e-7,     # Gradient tolerance\n    tol_p=1e-7,     # Parameter change tolerance\n    tol_c=1e-7,     # Chi-squared change tolerance\n    # ... other optional parameters\n)\n\nprint(f\"Fit converged: {conv}\")\nprint(f\"Iterations: {iters}\")\nprint(f\"Final Chi-squared: {chi2}\")\nprint(f\"Fitted parameters: {p_fit}\")\n# print(f\"Covariance matrix: {cov}\") # Covariance can be large\n```\n\n### Fitting pixel-wise on 3D data\n\nFor a 3D NumPy array where each `(row, col)` location has a curve along the third dimension (`data_cube[row, col, :]`), use `levenberg_marquardt_pixelwise`. This function parallelizes the fitting process across the `row` and `col` dimensions using `numba.prange`.\n\n```python\nimport numpy as np\nfrom lmba import levenberg_marquardt_pixelwise\n\n# Assume my_model is defined and JIT-compiled above\n\n# Generate some synthetic 3D data (replace with your actual data)\nrows, cols, depth = 100, 100, 50 # Example dimensions\nt_data = np.linspace(0.1, 25, depth, dtype=np.float64)\ndata_cube = np.empty((rows, cols, depth), dtype=np.float64)\n\np_true_base = np.array([5.0, 2.0, 2.0, 10.0], dtype=np.float64)\nrng = np.random.default_rng(42)\n\nfor r_idx in range(rows):\n    for c_idx in range(cols):\n        # Vary true params slightly per pixel\n        p_pixel_true = p_true_base * (1 + rng.uniform(-0.05, 0.05, size=p_true_base.shape))\n        y_clean_pixel = my_model(t_data, p_pixel_true)\n        noise_pixel = rng.normal(0, 0.1, size=depth).astype(np.float64)\n        data_cube[r_idx,c_idx,:] = (y_clean_pixel + noise_pixel).astype(np.float64)\n\n# Global initial guess for all pixels\np0_global = np.array([4.0, 1.5, 1.5, 8.0], dtype=np.float64)\n\n# Optional weights (applied to each pixel identically)\n# weights_1d = 1.0 / (0.1**2 + np.finfo(float).eps) # Assuming noise_std = 0.1\n\n# Run the pixel-wise fit (this is parallelized)\np_results, cov_results, chi2_results, n_iter_results, conv_results = levenberg_marquardt_pixelwise(\n    my_model,        # Your Numba-compiled model function\n    t_data,          # Independent variable (1D array, common for all pixels)\n    data_cube,       # 3D data array (rows x cols x depth)\n    p0_global,       # Global initial guess (1D array)\n    # Optional parameters for the core LM algorithm, passed to each pixel fit\n    # weights_1d=weights_1d,\n    max_iter=500,\n    tol_g=1e-6,\n    tol_p=1e-6,\n    tol_c=1e-6,\n    # ... other optional parameters\n)\n\nprint(f\"Pixel-wise fitting finished.\")\nprint(f\"Shape of fitted parameters: {p_results.shape}\") # (rows x cols x n_params)\nprint(f\"Shape of convergence flags: {conv_results.shape}\") # (rows x cols)\nprint(f\"Percentage converged: {np.sum(conv_results) / (rows*cols) * 100.0:.2f}%\")\n```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Tests\n\nThe library includes a test suite using `pytest` to verify the correctness of the core LM algorithm and the pixel-wise function against known solutions (for noiseless data) and against `scipy.optimize.least_squares` (for noisy data).\n\nTo run the tests:\n\n1.  Ensure you have installed the test dependencies: `pip install .[test]`\n2.  Navigate to the project root directory in your terminal.\n3.  Run pytest:\n    ```sh\n    pytest\n    ```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- ROADMAP --\u003e\n\n## Roadmap\n\n- [ ] Add support for analytical Jacobian functions (instead of only finite differences).\n- [ ] Implement parameter bounds.\n- [ ] Investigate alternative damping strategies (e.g., Nielsen's method).\n- [ ] Improve robustness for ill-conditioned problems.\n- [ ] Add more detailed documentation and examples.\n- [ ] Potentially publish on PyPI.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- CONTRIBUTING --\u003e\n\n## Contributing\n\nContributions are welcome! If you have suggestions or find bugs, please open an issue or submit a pull request.\n\n1.  Fork the Project\n2.  Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3.  Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4.  Push to the Branch (`git push origin feature/AmazingFeature`)\n5.  Open a Pull Request\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- LICENSE --\u003e\n\n## License\n\nDistributed under the [MIT License][license-url]. See `LICENSE` for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- CONTACT --\u003e\n\n## Contact\n\nMirza Arnaut - mirza.arnaut@tu-dortmund.de\n\nProject Link: https://github.com/arunoruto/lumafit\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- ACKNOWLEDGMENTS --\u003e\n\n## Acknowledgments\n\n- The original Levenberg-Marquardt algorithm (see references in `lmba/__init__.py`).\n- [Numba](https://numba.pydata.org/) for providing the acceleration capabilities.\n- [NumPy](https://numpy.org/) and [SciPy](https://scipy.org/) for fundamental numerical computing tools.\n- [pytest](https://docs.pytest.org/) for the testing framework.\n- [othneildrew/Best-README-Template](https://github.com/othneildrew/Best-README-Template) for the README structure template.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n\u003c!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --\u003e\n\n[contributors-shield]: https://img.shields.io/github/contributors/arunoruto/lumafit.svg?style=for-the-badge\n[contributors-url]: https://github.com/arunoruto/lumafit/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/arunoruto/lumafit.svg?style=for-the-badge\n[forks-url]: https://github.com/arunoruto/lumafit/network/members\n[stars-shield]: https://img.shields.io/github/stars/arunoruto/lumafit.svg?style=for-the-badge\n[stars-url]: https://github.com/arunoruto/lumafit/stargazers\n[issues-shield]: https://img.shields.io/github/issues/arunoruto/lumafit.svg?style=for-the-badge\n[issues-url]: https://github.com/arunoruto/lumafit/issues\n[license-shield]: https://img.shields.io/github/license/arunoruto/lumafit.svg?style=for-the-badge\n[license-url]: https://github.com/arunoruto/lumafit/blob/main/LICENSE\n[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge\u0026logo=linkedin\u0026colorB=555\n\n[linkedin-url]: https://linkedin.com/in/[your_linkedin_username]\n[Python.any]: https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white\n[Python-url]: https://www.python.org/\n[Numba-shield]: https://img.shields.io/badge/Numba-00A6FF?style=for-the-badge\u0026logo=numba\u0026logoColor=white\n[Numba-url]: https://numba.pydata.org/\n[NumPy-shield]: https://img.shields.io/badge/NumPy-013243?style=for-the-badge\u0026logo=numpy\u0026logoColor=white\n[NumPy-url]: https://numpy.org/\n[SciPy-shield]: https://img.shields.io/badge/SciPy-8FBC8F?style=for-the-badge\u0026logo=scipy\u0026logoColor=white\n[SciPy-url]: https://scipy.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farunoruto%2Flumafit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farunoruto%2Flumafit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farunoruto%2Flumafit/lists"}