{"id":16943969,"url":"https://github.com/jeremyagray/sigcalc","last_synced_at":"2025-04-05T14:43:39.056Z","repository":{"id":210466875,"uuid":"726301070","full_name":"jeremyagray/sigcalc","owner":"jeremyagray","description":"significant figures calculations","archived":false,"fork":false,"pushed_at":"2024-01-27T19:10:15.000Z","size":277,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-01-28T01:52:20.214Z","etag":null,"topics":["chemistry","physics","python","significant-figures"],"latest_commit_sha":null,"homepage":"https://github.com/jeremyagray/sigcalc/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeremyagray.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.rst","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":"2023-12-02T01:39:01.000Z","updated_at":"2024-05-27T19:32:55.280Z","dependencies_parsed_at":"2024-01-21T22:21:01.064Z","dependency_job_id":"4a689d95-b212-4853-9c92-54662e2f4eca","html_url":"https://github.com/jeremyagray/sigcalc","commit_stats":{"total_commits":26,"total_committers":1,"mean_commits":26.0,"dds":0.0,"last_synced_commit":"e4b5b3c01377b648f456fdffeb0b385e041ca505"},"previous_names":["jeremyagray/sigcalc"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyagray%2Fsigcalc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyagray%2Fsigcalc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyagray%2Fsigcalc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremyagray%2Fsigcalc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeremyagray","download_url":"https://codeload.github.com/jeremyagray/sigcalc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353676,"owners_count":20925325,"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":["chemistry","physics","python","significant-figures"],"created_at":"2024-10-13T21:15:47.854Z","updated_at":"2025-04-05T14:43:39.037Z","avatar_url":"https://github.com/jeremyagray.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":".. *****************************************************************************\n..\n.. sigcalc, significant figures calculations\n..\n.. Copyright 2023-2024 Jeremy A Gray \u003cgray@flyquackswim.com\u003e.\n..\n.. All rights reserved.\n..\n.. SPDX-License-Identifier: GPL-3.0-or-later\n..\n.. *****************************************************************************\n\n=========\n sigcalc\n=========\n\nSigcalc is a python module for expressing quantities with significant\nfigures and performing calculations on quantities based on the rules\nof significant figures.\n\n..\n   .. image:: https://badge.fury.io/py/sigcalc.svg\n      :target: https://badge.fury.io/py/sigcalc\n      :alt: PyPI Version\n   .. image:: https://readthedocs.org/projects/sigcalc/badge/?version=latest\n      :target: https://sigcalc.readthedocs.io/en/latest/?badge=latest\n      :alt: Documentation Status\n\nInstallation\n============\n\nInstall sigcalc with pip::\n\n  pip install sigcalc\n\nor with poetry::\n\n  poetry add sigcalc\n\n``sigcalc`` depends on the internal ``decimal``\n`module \u003chttps://docs.python.org/3/library/decimal.html\u003e`_\nfor arithmetic and `mpmath \u003chttps://mpmath.org/\u003e`_ for transcendental\nand other functions.\n\nUsage\n=====\n\nImport the ``Quantity`` class::\n\n  \u003e\u003e\u003e from sigcalc import Quantity\n  \u003e\u003e\u003e from decimal import getcontext\n  \u003e\u003e\u003e getcontext().prec = 28\n\nCreate ``Quantity`` objects as necessary::\n\n  \u003e\u003e\u003e a = Quantity(\"3.14\", \"3\")\n  \u003e\u003e\u003e b = Quantity(\"2.72\", \"3\")\n\nThe precision of the underlying ``decimal`` context should adjust\nautomatically to contain the number of digits specified or the number\nof significant figures, within the limits of the ``decimal`` module.\n\nAlternatively, create a ``Quantity`` object from a ``Decimal``::\n\n  \u003e\u003e\u003e a = Quantity.from_decimal(\"3.14\")\n  \u003e\u003e\u003e b = Quantity(\"3.14\", \"3\")\n  \u003e\u003e\u003e a == b\n  True\n\nThe resulting significant figures is derived from the places in the\nspecified value.\n\nOr generate randomly over a range::\n\n  \u003e\u003e\u003e a = Quantity.random(\"273.15\", \"373.15\")\n\nwhich is helpful for generating exercises for classes.\n\nArithmetic for ``Quantity`` objects is implemented on the usual magic\nmethods::\n\n  \u003e\u003e\u003e from sigcalc import Quantity\n  \u003e\u003e\u003e from decimal import getcontext\n  \u003e\u003e\u003e from decimal import ROUND_HALF_EVEN\n  \u003e\u003e\u003e getcontext().prec = 28\n  \u003e\u003e\u003e getcontext().rounding = ROUND_HALF_EVEN\n  \u003e\u003e\u003e a = Quantity(\"3.14\", \"3\")\n  \u003e\u003e\u003e b = Quantity(\"2.72\", \"3\")\n  \u003e\u003e\u003e a + b\n  Quantity(\"5.86\", \"3\")\n  \u003e\u003e\u003e a - b\n  Quantity(\"0.42\", \"2\")\n  \u003e\u003e\u003e a * b\n  Quantity(\"8.5408\", \"3\")\n  \u003e\u003e\u003e a / b\n  Quantity(\"1.154411764705882352941176471\", \"3\")\n  \u003e\u003e\u003e abs(a)\n  Quantity(\"3.14\", \"3\")\n  \u003e\u003e\u003e -a\n  Quantity(\"-3.14\", \"3\")\n  \u003e\u003e\u003e +a\n  Quantity(\"3.14\", \"3\")\n\nBeware that rounding is not performed during calculations and that\nreported significant figures for calculated values are for the\nunrounded value.  For example, a calculation that resulted in a result\nof ``Quantity(\"99.9\", \"3\")`` could round to ``Quantity(\"100.0\",\n\"4\")``, depending on the current rounding mode.\n\nNote that ``__floordiv__`` is not implemented as it is not useful for\nsignificant figures calculations::\n\n  \u003e\u003e\u003e a // b\n  Traceback (most recent call last):\n  TypeError: unsupported operand type(s) for //: 'Quantity' and 'Quantity'\n\nComparisons behave as expected for real numbers, with the exception\nequality and significance.  Since quantities with different\nsignificance have different meanings, they are not equal as quantity\nobjects::\n\n  \u003e\u003e\u003e from sigcalc import Quantity\n  \u003e\u003e\u003e a = Quantity(\"3.135\", \"3\")\n  \u003e\u003e\u003e b = Quantity(\"3.135\", \"4\")\n  \u003e\u003e\u003e c = Quantity(\"3.145\", \"3\")\n  \u003e\u003e\u003e a == a\n  True\n  \u003e\u003e\u003e a == b\n  False\n  \u003e\u003e\u003e a != b\n  True\n  \u003e\u003e\u003e a \u003c b\n  False\n  \u003e\u003e\u003e a \u003c= b\n  False\n\nEqual constants should be equal regardless of the significant figures\nof the instance.\n\nRounding affects comparisons as well::\n\n  \u003e\u003e\u003e from decimal import ROUND_HALF_EVEN\n  \u003e\u003e\u003e from decimal import ROUND_HALF_UP\n  \u003e\u003e\u003e from decimal import getcontext\n  \u003e\u003e\u003e getcontext().rounding = ROUND_HALF_EVEN\n  \u003e\u003e\u003e a \u003c c\n  False\n  \u003e\u003e\u003e a == c\n  True\n  \u003e\u003e\u003e a \u003c= c\n  True\n  \u003e\u003e\u003e getcontext().rounding = ROUND_HALF_UP\n  \u003e\u003e\u003e a \u003c c\n  True\n  \u003e\u003e\u003e a == c\n  False\n  \u003e\u003e\u003e a \u003c= c\n  True\n\nRounding and output are tied together.  Typically, rounding is\nunnecessary except for output but is available::\n\n  \u003e\u003e\u003e a = Quantity(\"3.14\", \"2\")\n  \u003e\u003e\u003e a.round()\n  Quantity(\"3.1\", \"2\")\n  \u003e\u003e\u003e a\n  Quantity(\"3.14\", \"2\")\n\nRounding constants has no effect::\n\n  \u003e\u003e\u003e a = Quantity(\"3.145\", \"3\", constant=True)\n  \u003e\u003e\u003e a.round()\n  Quantity(\"3.145\", \"28\", constant=True)\n\nString output uses the underlying ``decimal`` module's string output\nafter rounding to the correct significant figures::\n\n  \u003e\u003e\u003e from decimal import ROUND_HALF_EVEN\n  \u003e\u003e\u003e from decimal import ROUND_HALF_UP\n  \u003e\u003e\u003e from decimal import getcontext\n  \u003e\u003e\u003e a = Quantity(\"3.145\", \"3\")\n  \u003e\u003e\u003e getcontext().rounding = ROUND_HALF_UP\n  \u003e\u003e\u003e str(a)\n  '3.15'\n  \u003e\u003e\u003e getcontext().rounding = ROUND_HALF_EVEN\n  \u003e\u003e\u003e str(a)\n  '3.14'\n\nThe rounding mode is controlled by the ``decimal`` module contexts and\ncontext managers.  The default rounding mode for the ``decimal``\nmodule is ``decimal.ROUND_HALF_EVEN`` while the rounding used in most\ntextbook discussions of significant figures is\n``decimal.ROUND_HALF_UP``, so beware.\n\nLikewise with formatting::\n\n  \u003e\u003e\u003e getcontext().rounding = ROUND_HALF_UP\n  \u003e\u003e\u003e format(a, \".2e\")\n  '3.15e+0'\n  \u003e\u003e\u003e getcontext().rounding = ROUND_HALF_EVEN\n  \u003e\u003e\u003e format(b, \".2e\")\n  '3.14e+0'\n\nPower and Square Root Functions\n-------------------------------\n\nThe power and square root (``__pow__()`` and ``sqrt()``) functions and\nare implemented as wrappers around the appropriate functions from\n``decimal.Decimal``, calculating results based on the ``value`` of a\n``Quantity`` combined with the correct significant figures, following\nthe \"significance in, significance out\" rule for both functions.\n\nExponential and Logarithmic Functions\n-------------------------------------\n\nThe exponential and logarithmic (``exp()``, ``exp10()``, ``ln()``, and\n``log10()``) functions are implemented as wrappers around the\ncorresponding functions from ``decimal`` to calculate the ``value`` of\na ``Quantity`` combined with the correct significant figures.\nAbscissa digits are treated as placeholders so a logarithm will\nincrease significance by the number of significant abscissa digits;\nexponentials will decrease the significance by the number of\nsignificant abscissa digits.  Consequently, if a ``Quantity`` has\nsignificant figures less than or equal to the number of abscissa\ndigits, a ``RuntimeWarning`` will be raised and a ``Quantity`` with\nzero significant figures will be returned.  See the references for\nmore information.\n\nTranscendental Functions\n------------------------\n\nThe transcendental functions and their inverses are implemented as\nwrappers around the appropriate functions from ``mpmath``, calculating\nresults based on the ``value`` of a ``Quantity`` combined with the\ncorrect significant figures, following the \"significance in,\nsignificance out\" rule.\n\nHyperbolic Functions\n--------------------\n\nThe hyperbolic functions and their inverses are implemented as\nwrappers around the appropriate functions from ``mpmath``, calculating\nresults based on the ``value`` of a ``Quantity`` combined with the\ncorrect significant figures, following the \"significance in,\nsignificance out\" rule.\n\nReferences\n==========\n\n``sigcalc`` implements significant figures calculations as commonly\ndescribed in high school and undergraduate chemistry and physics\ntextbooks, examples of which may be found at:\n\n1. `Significant Figures at Wikipedia \u003chttps://en.wikipedia.org/wiki/Significant_figures\u003e`_\n2. `Significance Arithmetic at Wikipedia \u003chttps://en.wikipedia.org/wiki/Significance_arithmetic\u003e`_\n3. Myers, R.T.; Tocci, S.; Oldham, K.B., Holt Chemistry, Holt, Rinehart and Winston: 2006.\n4. `\"How many significant figures in 0.0\" \u003chttps://math.stackexchange.com/questions/2149316/\u003e`_\n\nThanks to the developers of Python's ``decimal``\n`module \u003chttps://docs.python.org/3/library/decimal.html\u003e`_,\nthe `mpmath \u003chttps://mpmath.org/\u003e`_ library, and the\n`hypothesis \u003chttps://hypothesis.readthedocs.io/\u003e`_ testing library,\nwithout which, this would be a much smaller and less functional\nlibrary.\n\nThanks also to LibreTexts Mathematics for their reference on `hyperbolic functions \u003chttps://math.libretexts.org/Courses/Monroe_Community_College/MTH_211_Calculus_II/Chapter_6%3A_Applications_of_Integration/6.9%3A_Calculus_of_the_Hyperbolic_Functions\u003e`_.\n\nRemember, calculating with significant figures is not a substitute for\nrepetition of measurements and proper statistical analysis.\n\nCopyright and License\n=====================\n\nSPDX-License-Identifier: `GPL-3.0-or-later \u003chttps://spdx.org/licenses/GPL-3.0-or-later.html\u003e`_\n\nsigcalc, significant figures calculations\n\nCopyright (C) 2023-2024 `Jeremy A Gray \u003cgray@flyquackswim.com\u003e`_.\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or (at\nyour option) any later version.\n\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\nGeneral Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see https://www.gnu.org/licenses/.\n\nAuthor\n======\n\n`Jeremy A Gray \u003cgray@flyquackswim.com\u003e`_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremyagray%2Fsigcalc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeremyagray%2Fsigcalc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremyagray%2Fsigcalc/lists"}