diff --git a/doc/Makefile b/doc/Makefile index dca8b3b2..ecd46cbf 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,7 +20,6 @@ ALLSPHINXOPTS = $(SPHINX_OUTPUT) $(SPHINXOPTS) . html: gallery cp sphinx/ext_mathjax.py extensions.py $(SPHINXBUILD) -b html $(SPHINX_OUTPUT) $(SPHINX_OPTS) . $(BUILDDIR)/html - ./filter_spurious_link_from_html.py @echo @echo "html build finished: $(BUILDDIR)/html." @@ -38,7 +37,6 @@ examples/index.rst: htmlzip: html cp sphinx/ext_mathjax.py extensions.py $(SPHINXBUILD) -b html $(SPHINX_OUTPUT) $(SPHINX_OPTS) . $(BUILDDIR)/lmfit_doc - ./filter_spurious_link_from_html.py cd $(BUILDDIR) && zip -pur html/lmfit_doc.zip lmfit_doc epub: gallery diff --git a/doc/model.rst b/doc/model.rst index 9463856b..446607a3 100644 --- a/doc/model.rst +++ b/doc/model.rst @@ -598,6 +598,59 @@ of: With that definition, the value (and uncertainty) of the ``fwhm`` parameter will be reported in the output of any fit done with that model. +.. _model_data_coercion_section: + +Data Types for data and independent data with ``Model`` +------------------------------------------------------------- + +The model as defined by your model function will use the independent +variable(s) you specify to best match the data you provide. The model is meant +to be an abstract representation for data, but when you do a fit with +:meth:`Model.fit`, you really need to pass in values for the data to be modeled +and the independent data used to calculate that data. + +The mathematical solvers used by ``lmfit`` all work exclusively with +1-dimensional numpy arrays of datatype (dtype) ``float64``. The value of the +calculation ``(model-data)*weights`` using the calculation of your model +function, and the data and weights you pass in *will be coerced* to an +1-dimensional ndarray with dtype ``float64`` when it is passed to the solver. + +If the data you pass to :meth:`Model.fit` is not an ndarray of dtype +``float64`` but is instead a tuples of numbers, a list of numbers, or a +``pandas.Series``, it will be coerced into an ndarray. If your data is a list, +tuple, or Series of complex numbers, it *will be coerced* to an ndarray with +dtype ``complex128``. + +If your data is a numpy array of dtype ``float32``, it *will not be coerced* to +``float64``, as we assume this was an intentional choice. That may make all of +the calculations done in your model function be in single-precision which may +make fits less sensitive, but the values will be converted to ``float64`` +before being sent to the solver, so the fit should work. + +The independent data for models using ``Model`` are meant to be truly +independent, and not **not** required to be strictly numerical or objects that +are easily converted to arrays of numbers. That is, independent data for a +model could be a dictionary, an instance of a user-defined class, or other type +of structured data. You can use independent data any way you want in your +model function. + +But, as with almost all the examples given here, independent data is often also +a 1-dimensonal array of values, say ``x``, and a simple view of the fit would be +to plot the data as ``y`` as a function of ``x``. Again, this is not required, but +it is very common. Because of this very common usage, if your independent data +is a tuple or list of numbers or ``pandas.Series``, it *will be coerced* to be +an ndarray of dtype ``float64``. But as with the primary data, if your +independent data is an ndarray of some different dtype (``float32``, +``uint16``, etc), it *will not be coerced* to ``float64``, as we assume this +was intentional. + +.. note:: + + Data and independent data that are tuples or lists of numbers, or + ``panda.Series`` will be coerced to an ndarray of dtype ``float64`` before + passing to the model function. Data with other dtypes (or independent data + of other object types such as dicts) will not be coerced to ``float64``. + .. _model_saveload_sec: diff --git a/doc/whatsnew.rst b/doc/whatsnew.rst index 76cf62bb..d8fb9c9d 100644 --- a/doc/whatsnew.rst +++ b/doc/whatsnew.rst @@ -13,22 +13,37 @@ consult the `lmfit GitHub repository`_. .. _whatsnew_120_label: -Version 1.2.0 Release Notes (March XX, 2023) +Version 1.2.0 Release Notes (April 05, 2023) ================================================= New features: - add ``create_params`` function (PR #844) +- add ``chi2_out`` and ``nsigma`` options to ``conf_interval2d()`` +- add ``ModelResult.summary()`` to return many resulting fit statistics and attributes into a JSON-able dict. +- add ``correl_table()`` function to ``lmfit.printfuncs`` and ``correl_mode`` option to ``fit_report()`` and + ``ModelResult.fit_report()`` to optionally display a RST-formatted table of a correlation matrix. Bug fixes/enhancements: -- fix deepcopy of ``Parameters`` (mguhyo; PR #837) +- fix bug in reported uncertainties for constrained parameters by better propating uncertainties (Issue #855; PR #856) +- Coercing of user input data and independent data for ``Model`` to float64 ndarrays is somewhat less aggressive and + will not increase the precision of numpy ndarrays (see :ref:`model_data_coercion_section` for details). The resulting + calculation from a model or objective function is more aggressively coerced to float64. (Issue #850; PR #853) +- the default value of ``epsfcn`` is increased to 1.e-10 to allow for handling of data with precision less than float64 + (Issue #850; PR #853) +- fix ``conf_interval2d`` to use "increase chi-square by sigma**2*reduced chi-square" to give the ``sigma``-level + probabilities (Issue #848; PR #852) +- fix reading of older ``ModelResult`` (Issue #845; included in PR #844) +- fix deepcopy of ``Parameters`` and user data (mguhyo; PR #837) - improve ``Model.make_params`` and ``create_params`` to take optional dict of Parameter attributes (PR #844) -- fix reporting of ``nfev`` from ``least_squares`` to better reflect actual number of function calls (PR #844) +- fix reporting of ``nfev`` from ``least_squares`` to better reflect actual number of function calls (Issue #842; PR #844) - fix bug in ``Model.eval`` when mixing parameters and keyword arguments (PR #844, #839) - re-adds ``residual`` to saved ``Model`` result (PR #844, #830) -- ``ConstantModel`` and ``ComplexConstantModel`` will return an ndarray of the same shape as the independent variable ``x`` (JeppeKlitgaard, Issue #840; PR #841) +- ``ConstantModel`` and ``ComplexConstantModel`` will return an ndarray of the same shape as the independent variable + ``x`` (JeppeKlitgaard, Issue #840; PR #841) - update tests for latest versions of NumPy and SciPy. +- many fixes of doc typos and updates of dependencies, pre-commit hooks, and CI. .. _whatsnew_110_label: