.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "introduction_examples/plot_basic_example_walk_through.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_introduction_examples_plot_basic_example_walk_through.py: Linear Python Model Example ================================== This section applies many of the topics introduced in the previous chapter to a simple calibration of the equation of a line (:math:`y=\text{m}x+\text{b}`) to data. While the example is simple it contains all of the fundamental topics necessary for more advanced calibrations. At the top of all Python files is typically the location where all of the modules are imported. Here we import all of MatCal's tools. .. GENERATED FROM PYTHON SOURCE LINES 15-18 .. code-block:: Python from matcal import * .. GENERATED FROM PYTHON SOURCE LINES 19-25 We use the ``from <> import *`` format to import all of the user facing objects and functions into Python from MatCal. The first thing to do in a MatCal study is to define what are our parameters of interest. For this example, a line is being optimized to fit a set of data; therefore, there are two parameters of interest: the slope and the y intercept. .. GENERATED FROM PYTHON SOURCE LINES 27-28 .. code-block:: Python slope = Parameter('slope', 0, 10, 9.9) .. GENERATED FROM PYTHON SOURCE LINES 29-38 In the previous line, a :class:`~matcal.core.parameters.Parameter` object is created and assigned to ``slope``. The :class:`~matcal.core.parameters.Parameter` class is used by MatCal to designate and characterize the parameters of interest. The parameter class has three mandatory ordered arguments: the parameter name, a lower bound, and an upper bound. The parameter name is the name that the model will use to look up the parameter value. The lower and upper bounds bracket the parameter investigation range. .. GENERATED FROM PYTHON SOURCE LINES 38-40 .. code-block:: Python y_int = Parameter('y0', -10, 10) .. GENERATED FROM PYTHON SOURCE LINES 41-56 Here another :class:`~matcal.core.parameters.Parameter` object is created for the y-intercept. There are a couple differences in this object instantiation versus the previous. First, the parameter name and the name of the variable storing the parameter object do not have the same name. In practice, it is useful to make sure that those names are similar, because it makes the code more readable. Second, the parameter object is taking in four inputs instead of three. The fourth input is optional and will dictate the current parameter value. If no current value is passed as an argument, the current value is assigned to be the midpoint between the lower and upper bound. Next the parameters are bundled together into a :class:`~matcal.core.parameters.ParameterCollection`. .. GENERATED FROM PYTHON SOURCE LINES 56-57 .. code-block:: Python my_parameters = ParameterCollection('line parameters', slope, y_int) .. GENERATED FROM PYTHON SOURCE LINES 58-66 This is an object that holds the parameters and makes it easier to move the related set of parameters around. There are other types of Collections in MatCal that behave in a similar manner. To create the collection a collection name is passed into the constructor followed by all items to become part of the collection separated by commas. Now that the parameters of interest have been defined, we can create a MatCal study to act on these parameters. .. GENERATED FROM PYTHON SOURCE LINES 66-69 .. code-block:: Python my_calibration = GradientCalibrationStudy(my_parameters) my_calibration.set_results_storage_options(results_save_frequency=len(my_parameters)+1) .. GENERATED FROM PYTHON SOURCE LINES 70-88 The central MatCal tool is a study. As discussed in :ref:`MatCal Studies`, a study will assess how the parameters affect a model's response when compared to a set of data using an objective. In this case, the goal is to calibrate the slope and y-intercept of a line to match a set of data. Therefore, a :class:`~matcal.dakota.local_calibration_studies.GradientCalibrationStudy` is created. The :class:`~matcal.dakota.local_calibration_studies.GradientCalibrationStudy` will use gradient descent to calibrate the parameters it is given to a set of data when a model and objective is provided. A MatCal study evaluates the effects of its parameters on evaluation sets that have been added to the study. An evaluation set is a collection of three concepts: a model, instructions on how to compare the model results to some reference data, and the reference data. To add an evaluation set first each of these components need to be defined. The first of this triad that will be defined is the reference data: .. GENERATED FROM PYTHON SOURCE LINES 88-91 .. code-block:: Python my_data = FileData('my_data_file.csv') .. GENERATED FROM PYTHON SOURCE LINES 92-101 MatCal typically expects reference data to be contained in external data files. MatCal can read several common types of data files using the :func:`~matcal.core.data_importer.FileData`, such as csv and npy. In the above line, MatCal reads in 'my_data_file.csv' and converts it into an object it can use. In this case there is only one set of data of interest located in the file 'my_data_file.csv'. The next component to create is the model. .. GENERATED FROM PYTHON SOURCE LINES 101-113 .. code-block:: Python def my_function(**parameters): import numpy as np time = np.linspace(0,100) slope = parameters['slope'] y0 = parameters['y0'] values = y0 + slope * time results = {'time':time, 'Y': values} return results my_model = PythonModel(my_function) .. GENERATED FROM PYTHON SOURCE LINES 114-130 Above we define a simple Python function that takes in a dictionary of the parameters of interest and returns a dictionary containing processed values. This function will be the model used by MatCal to calibrate the line parameters to the data. The function ``my_function`` unpacks the parameter dictionary using Python's unpacking feature ``**``. The keywords that MatCal assigns the different parameters are the same as the name supplied by the user in the creation of the parameters. MatCal can use this function as a model using the :class:`~matcal.core.models.PythonModel` class, where the only input is our ``my_function`` Python function. The last of the evaluation set triad is the instructions on how to compare the model results to the reference data. In MatCal, these instructions are conveyed to the study by creating an objective. .. GENERATED FROM PYTHON SOURCE LINES 130-133 .. code-block:: Python my_objective = CurveBasedInterpolatedObjective('time','Y') .. GENERATED FROM PYTHON SOURCE LINES 134-151 In the above line, a :class:`~matcal.core.objective.CurveBasedInterpolatedObjective` is created. This objective is an l2-norm of the differences between two curves in two dimensions and is the most commonly used objective in MatCal studies. :class:`~matcal.core.objective.CurveBasedInterpolatedObjective` takes in at least two string inputs. The first input string is the independent variable that will be used to parameterize the comparison of the dependent variables (the X-Axis). The second input string, and beyond, are the dependent variables that will be compared. In this example we use 'time' as our independent variable and 'Y' as our dependent variable. For our objective to work correctly, the data that we read in from 'my_data_file.csv' needs to have 'time' and 'Y' fields. In addition, our model needs to also produce 'time' and 'Y' value results. To add the evaluation set to the study the line below is called. .. GENERATED FROM PYTHON SOURCE LINES 151-153 .. code-block:: Python my_calibration.add_evaluation_set(my_model, my_objective, my_data) .. GENERATED FROM PYTHON SOURCE LINES 154-158 Now the study has the means to calibrate the parameters. It is possible for a study to have more than one evaluation set if applicable, but that will be discussed in a later example. To run the study the following line is used. .. GENERATED FROM PYTHON SOURCE LINES 158-160 .. code-block:: Python results = my_calibration.launch() .. GENERATED FROM PYTHON SOURCE LINES 161-171 The :meth:`~matcal.dakota.local_calibration_studies.GradientCalibrationStudy.launch` method begins the study, and will run until either the calibration completes, or it encounters an error. If the study completes successfully, it will return a dictionary of results including the calibrated parameters, and it will also create a file saving the best parameter values. MatCal's progress is recorded in "matcal.log", and, if the study encounters an error, details of the error will be stored there. More information on MatCal's output and results can be found at :ref:`Results and Plotting`. .. GENERATED FROM PYTHON SOURCE LINES 171-176 .. code-block:: Python make_standard_plots('time') print(f"Print best as results attribute:\n{results.best}") print(f"\nAccess and print y0 as attribute from best:\n{results.best.y0}") print(f"\nAccess and print best as dict:\n{results.best.to_dict()}") print(f"\nAccess and print best as list:\n{results.best.to_list()}") .. rst-class:: sphx-glr-horizontal * .. image-sg:: /introduction_examples/images/sphx_glr_plot_basic_example_walk_through_001.png :alt: plot basic example walk through :srcset: /introduction_examples/images/sphx_glr_plot_basic_example_walk_through_001.png :class: sphx-glr-multi-img * .. image-sg:: /introduction_examples/images/sphx_glr_plot_basic_example_walk_through_002.png :alt: plot basic example walk through :srcset: /introduction_examples/images/sphx_glr_plot_basic_example_walk_through_002.png :class: sphx-glr-multi-img * .. image-sg:: /introduction_examples/images/sphx_glr_plot_basic_example_walk_through_003.png :alt: plot basic example walk through :srcset: /introduction_examples/images/sphx_glr_plot_basic_example_walk_through_003.png :class: sphx-glr-multi-img .. rst-class:: sphx-glr-script-out .. code-block:: none Print best as results attribute: slope: 5.0 y0: 4.0 Access and print y0 as attribute from best: 4.0 Access and print best as dict: OrderedDict({'slope': 5.0, 'y0': 4.0}) Access and print best as list: [5.0, 4.0] .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 8.160 seconds) .. _sphx_glr_download_introduction_examples_plot_basic_example_walk_through.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_basic_example_walk_through.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_basic_example_walk_through.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_basic_example_walk_through.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_