.. _quickstart: ========== Quickstart ========== To get quickly up to speed lets try an example run using TauREx3. We will be using the ``examples/parfiles/quickstart.par`` file as a starting point and ``examples/parfiles/quickstart.dat`` as our observation. Copy these to a new folder somewhere. If you would rather work through the same ideas interactively, see the :ref:`notebook_walkthroughs`. Prerequisites ------------- Before reading this you should have a few things on hand. Firstly ``H2O`` and ``CO2`` absorption cross sections in one of the :ref:`supported_data_formats` is required. This example assumes cross-sections at *R=10000*. Secondly some collisionally induced absorption (CIA) cross sections are also required for a later part for ``H2-He`` and ``H2-H2``, you can get these from the HITRAN_ site. .. tip:: A starter set of these cross-sections and cia can be found in this dropbox: https://www.dropbox.com/sh/13y33d02vh56jh2/AABxuHdrZI83bSgoLz1Wzb2Fa?dl=0 Setup ------ In order to begin running forward models we need to tell *TauREx3* where our cross-sections are. We can do this by defining an ``xsec_path`` for cross sections and ``cia_path`` for CIA cross-sections under the ``[Global]`` header in our ``quickstart.par`` files like so:: [Global] xsec_path = /path/to/xsec cia_path = /path/to/cia Forward Model ------------- Using our input we can run and plot the forward model by doing:: taurex -i quickstart.par --plot And we should get: .. figure:: _static/firstfm.png :align: center Our first forward model Lets try plotting it against our observation. Under the ``[Observation]`` header we can add in the ``observed_spectrum`` keyword and point it to our ``quickstart.dat`` file like so:: [Observation] observed_spectrum = /path/to/quickstart.dat Now the spectrum will be binned to our observation: .. figure:: _static/fm_obs_bin.png :align: center Our binned observation You may notice that general structure and peaks don't seem to match up with observation. Our model doesn't seem to do the job and it may be the fault of our choice of molecule. Lets move on to chemistry. Chemistry --------- As we've seen, ``CO2`` doesn't fit the observation very well, we should try adding in another molecule. Underneath the ``[Chemistry]`` section we can add another sub-header with the name of our molecule, for this example we will use a ``constant`` gas profile which keeps it abundance constant throughout the atmosphere, there are other more complex profiles but for now we'll keep it simple:: [Chemistry] chemistry_type = taurex fill_gases = H2,He ratio=4.8962e-2 [[H2O]] gas_type = constant mix_ratio=1.1185e-4 [[CO2]] gas_type=constant mix_ratio=1.1185e-4 [[N2]] gas_type = constant mix_ratio = 3.00739e-9 Plotting it gives: .. image:: _static/co2_and_h2o.png We're getting there. It looks like H2O is definately there but maybe ``CO2`` isn't? Lets try it by commenting it out:: [Chemistry] chemistry_type = taurex fill_gases = H2,He ratio=4.8962e-2 [[H2O]] gas_type = constant mix_ratio=1.1185e-4 #[[CO2]] #gas_type=constant #mix_ratio=1.1185e-4 [[N2]] gas_type = constant mix_ratio = 3.00739e-9 .. image:: _static/h2o_only.png Much much better! We're still missing something though... Contributions ------------- It seems moelcular absorption is not the only process happening in the atmosphere. Looking at the shorter wavelengths we see the characteristic behaviour of **Rayleigh scattering** and a little from **collisionally** **induced** **absorption**. We can easily add these contributions under the ``[Model]`` section of the input file. Each *contribution* is represented as a subheader with additional arguments if necessary. By default we have contributions from molecular ``[[Absorption]]`` Lets add in some ``[[CIA]]`` from ``H2-H2`` and ``H2-He`` and ``[[Rayleigh]]`` scattering to the model:: [Model] model_type = transmission [[Absorption]] [[CIA]] cia_pairs = H2-He,H2-H2 [[Rayleigh]] .. image:: _static/ray_and_cia.png Hey not bad!! It might be worth seeing how each of these processes effect the spectrum. Easy, we can run ``taurex`` with the ``-c`` argument which plots the basic contributions:: taurex -i quickstart.par --plot -c .. image:: _static/contrib.png If you want a more detailed look of the each contribution you can use the ``-C`` option instead:: taurex -i quickstart.par --plot -C .. image:: _static/full_contrib.png Pretty cool. We're almost there. Lets save what we have now to file. Storage ------- ``Taurex3`` uses the HDF5_ format to store its state and results. We can accomplish this by using the ``-o`` output argument:: taurex -i quickstart.par -o myfile.hdf5 We can use this output to plot profiles spectra and even the optical depth! Try:: taurex-plot -i myfile.h5 -o fm_plots/ --all To plot everything: .. list-table:: * - .. figure:: _static/fm_plots/fm_plots-0.png :align: center Chemistry - .. figure:: _static/fm_plots/fm_plots-1.png :align: center Spectrum * - .. figure:: _static/fm_plots/fm_plots-2.png :align: center Contributions - .. figure:: _static/fm_plots/fm_plots-3.png :align: center Optical depth ``HDF5`` has many viewers such as HDFView_ or HDFCompass_ and APIs such as Cpp_, FORTRAN_ and Python_. Pick your poison. Retrieval --------- So we're close to the observation but not quite there and I suspect its the temperature profile. We should try running a retrieval. We will use nestle_ as our optimizer of choice but other brands are available. This has already be setup under the ``[Optimizer]`` section of the input file so we will not worry about it now. We now need to inform the optimizer what parameters we need to fit. The ``[Fitting]`` section should list all of the parameters in our model that we want (or dont want) to fit and *how* to go about fitting it. By default the ``planet_radius`` parameter is fit when no section is provided, we should start by creating our ``[Fitting]`` section and disabling the ``planet_radius`` fit:: [Fitting] planet_radius:fit = False the syntax is pretty simple, its essentially ``parameter_name:option`` with ``option`` being either ``fit``, ``bounds`` and ``mode``. ``fit`` is simply tells the optimizer whether to fit the parameter, ``bounds`` describes the parameter space to optimize in and ``mode`` instructs the optimizer to fit in either ``linear`` or ``log`` space. The parameter we are interested in is isothermal temperature which is represented as ``T``, and we will fit it within *1200 K* and *1400 K*:: [Fitting] planet_radius:fit = False T:fit = True T:bounds = 1200.0,1400.0 We don't need to include ``mode`` as by default ``T`` fits in linear space. Some parameters such as abundances fit in log space by default. Running taurex like before will just plot our forward model. To run the retrieval we simply add the ``--retrieval`` keyword like so:: taurex -i quickstart.par --plot -o myfile_retrieval.hdf5 --retrieval We should now see something like this pop up:: taurex.Nestle - INFO - ------------------------------------- taurex.Nestle - INFO - ------Retrieval Parameters----------- taurex.Nestle - INFO - ------------------------------------- taurex.Nestle - INFO - taurex.Nestle - INFO - Dimensionality of fit: 1 taurex.Nestle - INFO - taurex.Nestle - INFO - Param Value Bound-min Bound-max ------- ------- ----------- ----------- T 1265.98 1200 1400 taurex.Nestle - INFO - it= 393 logz=1872.153686niter: 394 It should only take a few minutes to run. Once done we should get an output like this:: ---Solution 0------ taurex.Nestle - INFO - Param MAP Median ------- ------- -------- T 1375.97 1371.71 So the temperature should have been around *1370 K*, huh, and lets see how it looks. Lets plot the output:: taurex-plot -i myfile_retrieval.hdf5 -o retrieval_plots/ --all Our final spectrum looks like: .. figure:: _static/retrieval_plots/retrieval_plots-2.png :align: center Final result We can then see the posteriors: .. figure:: _static/retrieval_plots/retrieval_plots-1.png :align: center Posteriors Thats the basics of playing around with TauREx 3. You can try modifying the quickstart to do other things! Take a look at :ref:`inputfile` to see a list of parameters you can change! .. _HITRAN: https://hitran.org/cia/ .. _HDF5: https://www.hdfgroup.org/solutions/hdf5/ .. _HDFView: https://www.hdfgroup.org/downloads/hdfview/ .. _nestle: https://github.com/kbarbary/nestle .. _HDFCompass: https://support.hdfgroup.org/projects/compass/ .. _FORTRAN: https://support.hdfgroup.org/HDF5/doc/fortran/index.html .. _Cpp: https://support.hdfgroup.org/HDF5/doc/cpplus_RM/index.html .. _Python: https://www.h5py.org/