Settings file is written in YAML format and that brings many benefits: easy to write, clear to read, self-explanatory names, flexible and powerful. The concepts are organized in blocks that are translated to YAML thanks to the fixed indentation (we suggest 4 white-spaces). So, for example, the first level defines the different modules:

                    

input:
    # Here settings related with input module
    segment: # It defines a description of the input segment
        x: 2 # It defines the maximum size of x dimension of the segment to 2.
output:
    # Settings linked with the output
    # ...
retrieval:
    # Definition of inversion strategy
    # ...
...
            

When GRASP is called, the first step is to read settings and the second is to prepare the environment for the settings defined in the main structures. If the settings are not valid, an explicit error message will be printed. Please read the first line of it carefully to understand the error.

The settings parameters can also be defined by the command line. In this case, after the first argument (settings file name), extra settings parameters can be defined with the syntax key=value where key is the parameter name in "dot syntax". For example, in GRASP, it is equivalent to be called with the argument input.driver=sdata or to have defined in the settings file the following content:

input:
    driver: sdata
                

It is important to define clearly how the relative paths have to be defined in the settings files. Relative paths are always relative to the file that defines it. In the next section, the reader will learn about how to include other settings file inside of a settings file, but this rule will stay valid: Relative paths are defined from settings file that define it. In the case of usage of command line, relative paths are relative to the current working directory. In the case of absolute paths, all this complexity disappears but the results are less portables.

                    

output:
    segment:
        function: hdf
        stream: "GRASP_Banizoumbou_20080101_20080331_2x2+3286+1376.hdf"
    tile:
        function: [ ascii, hdf ] 
        stream: [ "GRASP_Banizoumbou_20080101_20080331.txt",
                "GRASP_Banizoumbou_20080101_20080331.hdf" ]
                

                    

output:
    segment:
        function: hdf
        stream: "GRASP_Banizoumbou_{tile_from(%Y%m%d)}_{tile_to(%Y%m%d)}_{segment_nx}x{segment_ny}//
        +{segment_corner_column(4)}+{segment_corner_row(4)}.hdf"
    tile:
        function: [ ascii, hdf ] 
        stream: [ "GRASP_Banizoumbou_{tile_from(%Y%m%d)}_{tile_to(%Y%m%d)}.txt",
                "GRASP_Banizoumbou_{tile_from(%Y%m%d)}_{tile_to(%Y%m%d)}.hdf" ]
                

The ensemble of characteristics available to be retrieved or simulated by GRASP is open to user selection in the settings file inside retrieval.constraints.characteristic section. An example of the general structure of them is showed below:

                
retrieval:
    constraints:
        characteristic[1]:
            type: characteristic_name
            retrieved: true
            mode[1]:
                initial_guess:
                    value:                          [0.0, 0.0, 0.0, 0.0, ...]
                    min:                            [0.0, 0.0, 0.0, 0.0, ...]
                    max:                            [0.0, 0.0, 0.0, 0.0, ...]
                    index_of_wavelength_involved:   [0.0, 0.0, 0.0, 0.0, ...]
                single_pixel:
                    smoothness_constraints:
                        difference_order: 0.0
                        lagrange_multiplier: 0.0
                multi_pixel:
                    smoothness_constraints:
                        derivative_order_of_X_variability:    0.0
                        lagrange_multiplier_of_X_variability: 0.0
                        derivative_order_of_Y_variability:    0.0
                        lagrange_multiplier_of_Y_variability: 0.0
                        derivative_order_of_T_variability:    0.0
                        lagrange_multiplier_of_T_variability: 0.0
                    
            mode[2]:
            
                ...
            
            mode[3]:
            
                ...
                
            ...
                
                

The number assigned at each characteristic has no relevance at all while coherence is maintained. The retrieved field can be set to 'true' if the corresponding characteristic is going to be a retrieved parameter in the inversion; or to 'false' if it is just a fixed value for the forward simulation. The number of modes included in each characteristic depends on the nature of each one. For characteristics representing optical or mycrophisical aerosol properties (size distribution or refractive index for example), the number of modes corresponds to the number of aerosol modes selected for the retrieval/simulation (tipically one or two if fine/coarse distinction is made). For characteristics representing surface properties three modes will be needed to describe the associated model; except for polarization that only one is nedeed. The fields present in initial_guess part contain one element for each wavelength following the structure provided in the SDATA file in the case of optical wavelength dependent characteristics; one element for each bin for size distribution related characteristics; and one element for other mycrophysical magnitudes or non-wavelength dependent optical characteristics. In the former case, index_of_wavelength_involved should be filled with zeros for all the corresponding bins. The rest of the elements included in single_pixel or multi_pixel parts are always formed by one single element.

The list of available characteristics can be found below:

4.1.2.1. Initial guess through the algorithm

Understanding GRASP inversion procedure means understanding how the algorithm is starting from an initial guess and obtains a results array. This is an iterative procedure explained in the literature and introduced in Section 2.3, “GRASP Scientific Core algorithm”. The purpose of this section is to explain how initial guess is represented inside the code as an array which evolves in each iteration until getting the result array. The following diagram shows how initial guess is read from settings file and translated into an internal array in the code. This detail could look very technical and related with the development but understanding of some internal concepts of the code helps to understand how it works. The following diagram shows this transformation:

Figure 4.1. Translation of settings file into initial guess array

Since the initial guess is defined in the settings, it is defined once for the entire segment (one should remember that GRASP can work in a multi-pixel approach). Sometimes, it is desirable to have a different initial guess for each pixel. In that case the already described mechanisms to establish the initial guess are not enough, and GRASP proposes another useful tool to modify the initial guess of each segment. This information is considered as part of the input because it contains pixel dependent information and will be defined in detail in the Section 4.2.3, “Input information for characteristics”.

Once the initial guess is loaded, it is set as first array of characteristics to be retrieved. Retrieval process iterates over it until it gets the results. The results of GRASP retrieval is the array with the same shape as the initial guess, but containing the results of retrieval of these parameters to match them with SDATA file. Then, the GRASP forward model is called using this results array, GRASP obtains the rest of the derived results it provides. So, we can talk about two kinds of results: basic results and derived products. The following diagram shows this process:

Figure 4.2. Evolution of retrieved characteristics during GRASP processing

To know all the details about the products obtained by GRASP, please see Section 4.3.1, “The list of GRASP output parameters”.

In order to harmonize all possibilities to add random noise to the measurements that are going to be retrieved in GRASP a new setting called add_random_noise in the inversion.noises group has been created. There are three possible values that this setting can take: disable, measurement_fitting (default) and sdata. These options will produce a different effect depending on which retrieval mode (forward or inversion) has been selected. Here it is a small description of the meaning of the options:

                
 mode: inversion
    
    inversion:
        regime: single_pixel
        
        convergence:
            minimization_convention: logarithm
            maximum_iterations_for_stopping: 35
            maximum_iterations_of_Levenberg-Marquardt: 35 
            threshold_for_stopping: 1.0e-3
            threshold_for_stopping_Q_iterations: 1e-12
            scale_for_finite_difference: 1.0e-5  
            normal_system_solver: sparse_matrix_solver 

        measurement_fitting:
            polarization: degree_of_polarization                

        noises:
            add_random_noise: measurement_fitting # | disable | sdata
            noise[1]:
                standard_deviation_synthetic: 0.1
                error_type:  relative
                standard_deviation:  0.05
                measurement_type[1]:
                    type: I
                    index_of_wavelength_involved: [ 1, 2, 3, 4 ]
            noise[2]:
                standard_deviation_synthetic: 0.01
                error_type:  absolute
                standard_deviation:  0.005
                measurement_type[1]:
                    type: tod
                    index_of_wavelength_involved: [ 1, 2, 3, 4 ]
...
                
                

The SDATA (sensor data) format is the original input data format of the GRASP code. It is a simple text format designed by the science team at the early stages of the development of the scientific code and it's the easiest way to create test data.

In the context of the GRASP project, the SDATA format has a number of pros:

It has also a number of cons:

Whatever the number and seriousness of the cons, one of the design objectives is to keep the code simple and flexible allowing the scientific community to play with the code. It does not make sense to implement a driver for a single user who wants to do some tests with GRASP. That's why this easy format is maintained by the developer team.

In the following description, the elements in fixed-width font are the snippets of content. The numeric values in these snippets (e.g. in 2 2 2 : NX NY NT) are given only as examples.

        

SDATA version 2.0
2   2   2  : NX NY NT

4  2008-01-04T13:15:00Z 70000.0  0  0 : NPIXELS TIMESTAMP HOBS_km NSURF IFGAS
1  1  1	 3286  1377   2.599	13.528   252.0	 100.0  6  0.443  0.490  0.565 ...
2  1  1	 3287  1377   2.657	13.528   242.0	 100.0  6  0.443  0.490  0.565 ...
1  2  1	 3286  1376   2.601	13.583   241.0	 100.0  6  0.443  0.490  0.565 ...
2  2  1	 3287  1376   2.658	13.583   239.0	 100.0  6  0.443  0.490  0.565 ...


4  2008-01-06T13:02:41Z 70000.0  0  0 : NPIXELS TIMESTAMP HOBS_km NSURF IFGAS
1  1  1	 3286  1377   2.599	13.528   252.0	 100.0  6  0.443  0.490  0.565 ...
2  1  1	 3287  1377   2.657	13.528   242.0	 100.0  6  0.443  0.490  0.565 ...
1  2  1	 3286  1376   2.601	13.583   241.0	 100.0  6  0.443  0.490  0.565 ...
2  2  1	 3287  1376   2.658	13.583   239.0	 100.0  6  0.443  0.490  0.565 ...
                

SDATA files have a simple structure:

2 2 2 : NX NY NT

A CELL is a set of neighbouring pixels, that form the base of a SEGMENT. Each CELL has a HEADER and a number of PIXELs, supposedly acquired at the same time.

The CELL HEADER contains:

4 2008-01-04T13:15:00Z 70000.0 0 0 : NPIXELS TIMESTAMP HOBS NSURF IFGAS

Each line of data after the CELL HEADER represents exactly one pixel, with all its fields. The Table 4.5, “The PIXEL structure” describes the order and type of these fields. For the types, the Fortran notation is used: array types are described with the dimensions of arrays between parentheses, and the ordering is such that the first index increases faster. Indices start from 1, not from 0 like in C. For instance, when one reads real(nwl) for wavelengths, that means that one has to read a list of nwl real values that represent wavelengths.

The field pixel[ipix].meas[nwl].meas_type[nip] of pixel structure is a special code which defines the type of measure. The following table describes the valid codes and their interpretation:

This chapter main goal is to describe how the angles should be defined to be used inside of GRASP code. The universal spirit of GRASP, where many different instruments coexist (from satellite to ground based measurements), creates challenges to define a homogeneous way of defining the angles, keeping a unique geometry. As it is shown in the figure Figure 4.4, “Definition of GRASP geometry” GRASP angles are defined to be considered as "normal" for satellite reference.

Figure 4.4. Definition of GRASP geometry

Since GRASP angles are defined using a satellite reference, it provokes some problems to define what we could call as an intuitive "ground based" reference system. That is why we are going to put special emphasis on the definition of the angles to these less intuitive applications. The intuitive reference for "ground based" measurements, in spherical geometry, is given as follows:

where the sub index "gb" makes reference to "ground based".

The conversion to the GRASP geometry is done as follows:

Here we propose some examples for better understanding of the process. Before defining the measurement angles introduced in the code, both "intuitive" and "GRASP", we need first to consider the instrument viewing angle for each scenario (θ_v, ϕ_v). The following figure and table will provide some examples of angles defined for the ground based applications.

Figure 4.5. Ground based angles definition example

Since sunphptometers are widely used with GRASP, the following table provides information specifically about these instruments, considering the instrument viewing angle for each scenario (θ_v, ϕ_v). They can be understood as the "movements of the motors". The process will be as follow:

instrument viewing angle -> angle in (intuitive) ground based -> angle in GRASP

In the case of nephelometer data angle definition, it is a bit different since only θ angle has to be defined, the rest of the angles will be ignored. To provide nephelometer data (phase matrix), the conversion to the GRASP geometry is done as follows:

While in many cases the input data is just represented by SDATA information, sometimes it is necessary to provide extra information for each pixel. The way to inject extra information to the algorithm is to do it through the initial guess. Sometimes, this is just because the user wants to provide different initial guesses for each pixel, or sometimes it is just input information. In the first case, this can be easily done by the imagedat files that will be described below. On the other hand, when a charactacteristic is defined as “retrieved=false”, it is taken as input information.

The “segment_imagedat” tool enables the user to provide an ASCII file containing the complete set of initial guesses for all the pixels. Following illustration is an example of how the imagedat files looks like:

Figure 4.6. Example of a possible use of imagedat

The columns in this ASCII file correspond to the pixels, and each row is associated with a different characteristic. The first column is just the enumeration of characteristics starting by 1. The total number of both columns and rows has to be consistent with the input file. The value “-999” can be assigned to the initial guesses which the user does not need to modify, in this case the value defined in the characteristics section of the settings file will be taken by default. This mechanism provides a very versatile tool to inject pixel-dependent data to the retrieval code, for adjusting the initial guess or just for providing external input information from climatologies, models, etc.

Sunphotometers are widely used with GRASP. They take measurements of sky radiance and direct sun. Many inversion strategies can be used to retrieve sunphotometer data, but this section will explain how to define input data. The information that runs inside of GRASP has to be pre-processed in order to screen clouds, calibrate and normalize the data.

Following Section 4.2.1, “The SDATA format”, the direct sun measurements can be described as AOD or TOD defined in Table 4.6, “Types of measurements” as measurements of type 11 or 12. At this point it is needed to take into account that if "ifgas" field is defined as 1 in the case of AOD, no gaseous absorption optical depth will be accounted, but in the case of TOD they will be subtracted. The gases also affect the radiance measurements but in lower magnitude. In the case of TOD + radiances with ifgas=1, the same model will be applied to all measurements. If AOD is used, some (minor) incongruences could come from the use of different models to calculate gases for AOD and for radiances.

Radiance measurements are defined with the constant MEAS_TYPE_I(41). Polarized measurements can be defined as Q,U (42, 43) or as polarization rate (44). It is also important to check how polarized data is going to be manipulated in the retrieval code based on inversion strategy defined in the settings file.

Note that all processing will be considering range corrected profile for one wavelength. The procedure for other profiles from different wavelengths are exactly the same. Range corrected profile implies that at least the background noise was subtracted and altitude corrections were applied to the raw signal, but if it's possible to consider all other corrections (electrical noise and overlap correction, dead time correction, gluing analog and photon-counting signals and all others that your system may have), you should apply them.

Step 1. Background noise subtraction and range correction.

Let B' be the estimation of the background noise. Usually B' is estimated as P(Z_B), accumulated and averaged around selected altitude Z_BZ, much higher than the maximum altitude of lidar extraction in step 2 (Z_max). For example with maximum altitude Z_max=15km, it is averaged around 30 km and accumulated for the whole period of lidar observation. The noise and range corrected signal will be:

S(Z_i) = (P(Z_i)-B')*Z_i²

Step 2. Altitude range selection and signal cropping.

The minimum Z_min and maximum Z_max altitudes are selected and the signal is cropped, so Z_min<Z_i<Z_max. The minimum altitude should be selected as low as possible, preferably in the region where the overlap correction could be correctly applied. The Z_max should be selected from the following considerations: maximum altitude where the noise levels of lidar measurement are acceptable and the amount of atmospheric aerosols is still noticeable.

In case if the lidar used is inclined The sounding zenith angle should be provided for the corresponding wavelenghts. The angle value should be placed in the position of the SZA corresponding to this wavelength. All SZA's for all vertical profile measurements should be the same. Vertically pointed lidar should have this value set to 0. Note: Keep in mind that retrieved aerosol vertical profiles will be retrieved for vertically projected altitudes, i.e. if your lidar is inclined, the maximum altitude of the profile will be equivalent to Z_max*cos(SZA).

Step 3. Backscatter of molecular profile

Backscatter vertical profile is calculated inside of GRASP based on standard atmosphere model for each lidar wavelength[1]:

β_mol(Z_i,λ) = N * σ(λ) * (P(Z_i)/P_SA) * (T_SA/T(Z_i))

        where:

Step 4. Reducing the number of points in profiles

GRASP/GARRLiC can use arbitrary altitude/range scale. However, to keep number of retrieved parameters reasonable and to fight higher noise contamination of lidar signals at higher altitudes, it is recommended to use a logarithmical altitude/range scale with N_Z points to represent aerosol profiles in the atmosphere. For that, we have to present all vectors (altitude/range vector and profiles of lidar signals) in logarithmically equidistant manner.

1. Move to logarithmic scale and find altitude/range step:

logarithmic scale: Z_i ^lg = lg(Z_i)

step in log scale: ΔZ = (Z_max ^lg - Z_min^lg)/N_Z

logarithmic altitude ranges (from h_k to h_k+1 ) for averaging data in logarithmically equidistant manner, k = 1 .. N_z: h_k = Z₀ ^lg + (k - 1) * ΔZ

2. Average the data profiles

A_k = (Σ_j=1ⁿ A_j(h_k, h_k+1) ) / n

        where:

After such procedure, the number of points in three main vectors reduced to N_Z points in logarithmically equidistant manner. These values should be placed in places corresponding to the zenith wieving (vza or θ_v) angles for the vavelenths corresponding to lidar or vertical measurements.

Hint: the altitude/range vectors for measurements at all wavelengths have to be the same.

Step 5. Profile normalization

Values of lidar signals (except for volume depolarization profiles) vary from instrument to instrument, from detector to detector, that is why GRASP/GARRLiC requires normalized lidar signal. For consistency with the molecular optical depth, the profile of the molecular backscatter inside the code has to be normalized as well. Normalized lidar and backscatter profiles:

A'_k = A_k / ∫_Zmin^Zmax A_k dZ

        where A represents profile of lidar signal or molecular backscatter.

Caution: integration have to be done using meters in altitudes.

At the end, for each wavelength you have to have normalized lidar profiles and altitude vector. Volume depolarization profiles don't need to be normalized, the only requirement for such observations is to be presented in the percentage range i.e. [1.0e-9, 100]

References: Anthony Bucholtz, Rayleigh-scattering calculations for the terrestrial atmosphere, Optical Society of America, 1995.

GRASP is able to retrieve and simulate nephelometer measurements. This section is devoted to the definition of the convention to properly account the units and measurement geometry of these instruments within GRASP standards.

The zero reference of scattering angles in GRASP is 180 °. Thus, in order to introduce the nephelometer geometry in GRASP sdata, only θ angle (zenith angle) has to be defined, the rest of the angles will be ignored. The conversion to the GRASP geometry is done as follows:

Where θ_G corresponds to sdata angles and θ_n to the scattering angles of the nephelometer.

GRASP measurement input corresponds to the normalized Phase Matrix element P_1,1, and the relation with scattering function is described below.

GRASP scattering phase function units are:

GRASP scattering phase function units are:

The relationship between both is represented by the following expression:

Which means that the normalized Phase Matrix element P_1,1 is defined as:

If polar neph measurements are used, an additional factor of 4* π is necessary to convert into the units in GRASP: μm-1Str-1 to μm-1.

The output from GRASP is quite complex and strongly dependent on the settings used. As it was discussed in Section 4.1.2, “Retrieved characteristics”, there are two kinds of output products: direct and derived. Direct results are the values directly inverted in the initial guess array, then after obtaining them, forward model is called one more time to obtain the derived products. The list of direct and derived products obtained depends on the data and the inversion strategy selected (defined in the settings file). This chapter contains a complete list of products that can be obtained with GRASP, but it does not mean that all of them can be obtained with all inversion strategies.

In the internal GRASP output structures there are some products that are repeated between direct products structure (array with the same shape as initial guess) and derived products. The reason is that for some applications they are direct information, for others they are derived results. This depends on input data and inversion strategy, defined in the settings file.

Before defining the output, we are going to define the size of some arrays. This information is needed to understand the list of the products. For example, when a product such as AOD is defined as many times as wavelengths, it is because the output will be wavelength dependent (a value for each wavelength):

The following list includes all products that can be obtained using GRASP:

In this section the GRASP classic output format is going to be described for both if the output.segment.stream setting parameter has been set to "screen", in this case all output information will be printed on terminal; or alternatively if a path to an ascii file is provided. However, note that there are more possibilities of GRASP output formatting which can differ from what is going to be shown here.

The GRASP classic output is divided in three main sections:

As it was explained in Section 4.1.2, “Retrieved characteristics” section, the retrieval algorithm works iteratively over an array of parameters (in its first definition it is called the initial guess), until it represents the best solution. This solution array has same shape as the initial guess (the same parameters and defined in the same position). Once it is obtained, a final call of the forward model with the resulting array provides a complete list of output products.

For some applications, it can be useful to use the forward model without inverting any data. It can be done easily in GRASP with the use of the setting parameter retrieval.mode=forward. When no retrieval is performed, just one call of forward model is performed. If in the initial guess array the user has set an aerosol model, it will be used inside of the forward model obtaining therefore an entire output structure, with information in all fields.

This procedure can be used also to reprocess some data. If output parameters of a retrieval are stored, then they can be set as initial guess and then, running GRASP with the same settings, except for retrieval.mode=forward the entire output can be obtained again. This procedure can be used to reprocess data with many objectives such as saving storage space (just save the output array of grasp and reprocess to obtain the rest, if it is needed) or obtaining extra products in the future.

The previous procedure can also help to simulate the input data. It is useful because a valid geometry is necessary in the input data to set an SDATA file. In this case, an aerosol model is set as an initial guess and the code works just for the forward run. Then, by using retrieval.debug.simulated_sdata_file parameter, the user can set a path to the simulated files. A SDATA file will be dump to that path where the geometry is the same and the measurements are filled with the output results of the forward run. Then, this SDATA file can be used to self-consistency tests, where synthetic data is retrieved.

In this approach the retrieved characteristics which determine the optical properties of aerosols are the size distribution, the real and imaginary refractive indexes, and the percentage of spherical particles (the non-spherical part is modeled as spheroids). The calculation of the radiative properties (phase matrix, scattering and absorption cross-sections) from these initial characteristics is made through four-dimensional look-up-tables called "Kernels".

The four dimensions of the Kernels are: the size parameter, sphericity and the real and the imaginary refractive indices. Due to the extensive nature of these kernels, this approach represents the less restricted methodology, because any possible combination of the represented characteristics can be obtained as the solution.

The lack of intrinsic restrictions of this approach (note that as in all GRASP retrievals, apriori constraints can be set for any characteristic) presents obvious advantages. However, the general nature of Kernels methodology normally requires input measurements containing a higher amount of information in comparison with other approaches.

There are three different ways to represent the aerosol size distribution, from the most general to the simplest: triangle bins, lognormal bins and precalculated lognormal bins. The corresponding characteristics names in the GRASP YAML settings file are: “size_distribution_triangle_bins”, “size_distribution_lognormal” and “size_distribution_precalculated_lognormal”. Independently of the selected representation of the aerosol size distribution, the rest of the steps of this methodology to obtain aerosol radiative properties are the same.

In the triangle bins representation the value of each bin is retrieved independently from the others, and it corresponds to the integrated value following the trapezoidal rule between the provided size limits. The lognormal bins approach is a simplified version of the former, where each aerosol size distribution mode is modeled as a gaussian function only represented by three parameters: the center, the standard deviation and the norm. The former value is the aerosol concentration of the corresponding mode. The precalculated lognormal bins size distribution represents a step further in the simplification of this characteristic. In this case each aerosol mode is also represented by a Gaussian function. However, the center and the standard deviation are fixed to a predefined value and only the norm (aerosol concentration) of each mode is retrieved.

The main retrieved aerosol products of this approach are the fractions of the total aerosol concentration of precalculated aerosol models. These precalculated models correspond to the main aerosol types established by all our previous experiences (Ex: smoke, urban, oceanic and dust). Each of these models correspond to a fixed particle size distribution and refractive indices, containing the already calculated phase matrix, and the extinction and absorption cross-sections. The total aerosol retrieved characteristics can be obtained by weighting the characteristics used to calculate each of these models by its corresponding volume concentration.

The significant reduction of retrieved parameters makes this approach very suitable for the retrieval of input measurements with a reduced amount of information. The absence of Kernels in the whole process makes this option by far the fastest of all. One of the main drawbacks of this methodology is the fact that the inversion is intrinsically constrained by the selected models. However, these models have been carefully selected to be suitable to cover almost all atmospheric situations. Moreover, they can be recalculated or extended in order to cover specific situations.

An example of the necessary settings to use this approach can be found below. Where in the phase matrix section the bin of each mode no longer represents the limit radius but the accounted aerosol models. Particle size distribution, refractive indexes and sphericity characteristics are substituted by another characteristic called "aerosol_model_concentration".

forward_model:

      phase_matrix:
          size_binning_method_for_triangle_bins: logarithm
          number_of_elements: 4
          kernels_folder: "models_ang35_wl22_optimized"
          radius:
              mode[1]:
                  bins: [ 1.,  2., 3., 4., 5. ]
                  
  .
  .
  .


  constraints:
      characteristic[1]:
          type: aerosol_model_concentration
          retrieved: true
          mode[1]:
              initial_guess:                       #smoke       #urban    #oceanic   #dust
                  value:                          [0.9,           0.4,      0.4,     0.4.,      0.4]
                  min:                            [0.000005, 0.000005, 0.000005, 0.000005, 0.000005]
                  max:                            [1.0,           1.0,      1.0,      1.0,      1.0]
                  index_of_wavelength_involved:   [0,               0,        0,        0,        0]
              single_pixel:
              .
              .
              .

      characteristic[2]:
          type: aerosol_concentration
          retrieved: true
          mode[1]:
              initial_guess:
                  value:                          [0.05   ]
                  min:                            [0.0001 ]
                  max:                            [5.0    ]
                  index_of_wavelength_involved:   [0      ]
              single_pixel:
              .
              .
              .

        

The chemistry approach can be seen somehow as an intermediate approach between Kernels and Models. In this case size distribution and sphericity percentage are directly retrieved as in the case of Kernels. However, instead of the refractive indexes, here the fractions of the total aerosol concentration corresponding to the different chemical components are retrieved. The refractive indices corresponding to each of these components are predefined. Thus, the weighted refractive indexes of all the fractions in combination with the particle size distribution and the sphericity parameter are used as input for the Kernels look-up-tables to calculate the radiative properties.

In comparison with the Models approach, where the radiative properties can only be linearly weighted, the refractive index presents an extra layer of complexity when they are mixed. Because the weighting methodology used to obtain the total refractive index retains information about the aerosol internal structure. Two mixing possibilities are available now in GRASP: an internal mixture, where a linear mixture of the different components is performed; but also a Maxwell-Garnett mixture is available, where one element is considered as the main host and the rest of the chemical elements are taken as inclusions inside of it.

In this case the necessary settings to use this approach are very similar to Kernels. The size distribution can be represented using the three already described possibilities in the Kernels approach. However, the refractive index characteristics are substituted by "particle_component_volume_fractions_linear_mixture" in the case of the linear mixture, or by "particle_component_fractions_chemical_mixture" in the case of a Maxwell-Garnett mixture. An extra section called "chemistry" has to be added in the Forward model part, where it is provided: the names of each chemical component accounted in the inversion, the soluble component (if necessary) and the path to the directory where these predefined refractive index look-up-tables are located.

    
    forward_model:

        aerosol:
            chemistry:
                folder: "chemistry_refractive_indexes/"
                soluble: "ammnm_ntrt"
                species:
                    mode[1]: [ 'black_carbon', 'mix_dust','iron_oxide','water']
                    
        phase_matrix:
            size_binning_method_for_triangle_bins: logarithm
            number_of_elements: 1
            kernels_folder: "KERNELS_BASE/"
            radius:
                mode[1]:
                    min: 0.05
                    max: 15.0
                    
    .
    .
    .


    constraints:
        characteristic[1]:
            type: size_distribution_triangle_bins
            retrieved: true
            mode[1]:
                initial_guess:
                    value:                        [1.4715e-05, 1.4715e-03, ..., 1.4715e-03, 1.4715e-05]
                    min:                          [0.00001,  0.00001,  ...,  0.00001,  0.00001]
                    max:                          [1.0,      1.0,      ...,      1.0,      1.0]
                    index_of_wavelength_involved: [0,        0,       ...,        0,        0]
            .
            .
            .
                        
        characteristic[2]:
            type: particle_component_volume_fractions_linear_mixture
            retrieved: true
            mode[1]:
                initial_guess:             #1         #2        #3         #4
                    value:                 [0.00001,       0.0001,      0.0001,      0.0001      ]
                    min:                   [0.000001,    0.000001,   0.000001,    0.000001   ]
                    max:                   [0.2,        1.0,       1.0,        1.0      ]
                    index_of_wavelength_involved:   [0,        0,      0,     0      ]
                .
                .
                .

        
            

The transport models approach constitutes the most complex methodology to model atmospheric aerosols. This approach has been designed to facilitate the interface between sophisticated aerosol transport models and GRASP code, both for forward modeling and retrieval. Normally, these complex transport models work simultaneously with a high number of different aerosol particles with specific size distributions, shape, optical characteristics, vertical distributions… In the rest of the GRASP approaches for aerosol modeling only one or two aerosol modes are considered which have all these aforementioned characteristics totally independent between each other. However, the GRASP transport model approach is not only an additional interface that enables the possibility to work with multiple independent aerosol modes. But it is also a tool that allows the conversion between the characteristics that define the particles in the aerosol transport models (as mass mixing ratio) to the normal microphysical and optical characteristics that are normally used in GRASP.

GRASP transport model approach consists of 5 main aerosol components similar to MERRA-2 and CAMS aerosol models: sulphate (SU), desert dust (DU), sea salt (SS), organic (OC) and black carbon (BC). Each component can exhibit hydrophobic or hydrophilic properties resulting in 15 aerosol tracers: hydrophilic sulphate (SU), five size bins for hydrophobic dust (DU) and hydrophilic sea salt (SS), hydrophobic and hydrophilic modes of organic (OC) and black carbon (BC) aerosol . The concentration and optical depth of each tracer in the model is refined through the mass mixing ratio. Furthermore, each of these aerosol modes count with its own vertical profile, particle size distribution, sphericity parameter and all the rest of optical characteristics. Note that the different aerosol tracers are externally mixed with vertically dependent mass mixing ratios to obtain the corresponding total aerosol optical properties.

An example of the necessary settings to define the additional aerosol parameters of the transport models can be found below:

                
                forward_model:
                    phase_matrix:            
                        size_binning_method_for_triangle_bins: logarithm
                        number_of_elements: 4 
                        use_transport_model: true
                        number_of_bins_for_lognormal_size_distribution: [ ^repeat(43;15) ]
                        transport_model: 
                            vertical_profile: column_average  #tracer_average
                            tracers:     ['du1', 'du2', 'du3', 'du4', 'du5','bc1','bc2','oc1','oc2','ss1', 'ss2', 'ss3', 'ss4', 'ss5','su1'  ]
                            hydrophilic: [  0,     0,     0,     0,     0,    0,    1,    0,    1,    1,     1,     1,     1,     1,    1   ]
                            #hydrophilic: [  0,     0,     0,     0,     0,    0,    0,    0,    0,    0,     0,     0,     0,     0,    0   ]
                            density:     [2500., 2650., 2650., 2650., 2650.,1000.,1000.,1800.,1800., 2200., 2200., 2200., 2200.,2200., 1700.]                            
                        kernels_folder:  'KERNELS_BASE' # 'merra2_data_base'
                        radius:
                            mode[1]: # du1
                                min: 0.08
                                max: 20.0
                            mode[2]: # du2
                                min: 0.08
                                max: 20.0
                            mode[3]: # du3
                                min: 0.08
                                max: 20.0
                            mode[4]: # du4
                                min: 0.08
                                max: 20.0
                            mode[5]: # du5
                                min: 0.08
                                max: 20.0
                            mode[6]: # bc1
                                min: 0.0001 #0.002
                                max: 5.0
                            mode[7]: # bc2
                                min: 0.0001 #0.002
                                max: 5.0
                            .
                            .
                            . 
            

Where “forward_model.phase_matrix.transport_model.tracers” refers to the 15 aerosol tracers. “forward_model.phase_matrix.transport_model.density” and “forward_model.phase_matrix.transport_model.hyfrophilic” mark correspondingly the density of dry tracers and their hygroscopic properties (“0” corresponds to hydrophobic and “1” corresponds to hydrophilic aerosol).

The rest of the aerosol characteristics are defined following the standard GRASP settings convention for different aerosol modes:

                
                constraints:
                    characteristic[1]: #1
                        type: size_distribution_lognormal
                        retrieved: true
                        mode[1]: 
                            initial_guess: 
                                value:                        [0.6576, 0.2828]
                                min:                          [0.1,   0.1]
                                max:                          [3.0,   0.9]
                                index_of_wavelength_involved: [^repeat(0;2)]
                            single_pixel:
                                a_priori_estimates:
                                    lagrange_multiplier:      [1.0e-03,  1.0e-03]
                                smoothness_constraints:
                                    difference_order: 0
                                    lagrange_multiplier: 0.0
                        mode[2]: 
                            initial_guess: 
                                value:                        [1.2436, 0.25]
                                min:                          [0.1,   0.1]
                                max:                          [3.0,   0.9]
                                index_of_wavelength_involved: [^repeat(0;2)]
                            single_pixel:
                                a_priori_estimates:
                                    lagrange_multiplier:      [1.0e-03,  1.0e-03]
                                smoothness_constraints:
                                    difference_order: 0
                                    lagrange_multiplier: 0.0
                        mode[3]: 
                            initial_guess: 
                                value:                        [2.2969, 0.344]
                                min:                          [0.1,   0.1]
                                max:                          [3.0,   0.9]
                                index_of_wavelength_involved: [^repeat(0;2)]
                            single_pixel:
                                a_priori_estimates:
                                    lagrange_multiplier:      [1.0e-03,  1.0e-03]
                                smoothness_constraints:
                                    difference_order: 0
                                    lagrange_multiplier: 0.0
                        mode[4]: 
                            initial_guess: 
                                value:                        [5.3645, 0.707]
                                min:                          [0.1,   0.1]
                                max:                          [6.0,   0.9]
                                index_of_wavelength_involved: [^repeat(0;2)]
                            single_pixel:
                                a_priori_estimates:
                                    lagrange_multiplier:      [1.0e-03,  1.0e-03]
                                smoothness_constraints:
                                    difference_order: 0
                                    lagrange_multiplier: 0.0
                        .
                        .
                        .
                

                    characteristic[2]: 
                                type: tracer_level_concentration
                                retrieved: true
                                mode[1]: 
                                    initial_guess: 
                                        value:                        [^repeat(0.007;72)]
                                        min:                          [^repeat(1e-15;72)]
                                        max:                          [^repeat(0.500;72)]
                                        index_of_wavelength_involved: [^repeat(0;72)]
                                    single_pixel:
                                        a_priori_estimates:
                                            lagrange_multiplier:      [^repeat(0;72)]
                                        smoothness_constraints:
                                            difference_order: 0
                                            lagrange_multiplier: 0.0
                                mode[2]: 
                                    initial_guess: 
                                        value:                        [^repeat(0.007;72)]
                                        min:                          [^repeat(1e-15;72)]
                                        max:                          [^repeat(0.500;72)]
                                        index_of_wavelength_involved: [^repeat(0;72)]
                                    single_pixel:
                                        a_priori_estimates:
                                            lagrange_multiplier:      [^repeat(0;72)]
                                        smoothness_constraints:
                                            difference_order: 0
                                            lagrange_multiplier: 0.0
                                mode[3]: 
                                    initial_guess: 
                                        value:                        [^repeat(0.007;72)]
                                        min:                          [^repeat(1e-15;72)]
                                        max:                          [^repeat(0.500;72)]
                                        index_of_wavelength_involved: [^repeat(0;72)]
                                    single_pixel:
                                        a_priori_estimates:
                                            lagrange_multiplier:      [^repeat(0;72)]
                                        smoothness_constraints:
                                            difference_order: 0
                                            lagrange_multiplier: 0.0
                                mode[4]: 
                                    initial_guess: 
                                        value:                        [^repeat(0.007;72)]
                                        min:                          [^repeat(1e-15;72)]
                                        max:                          [^repeat(0.500;72)]
                                        index_of_wavelength_involved: [^repeat(0;72)]
                                    single_pixel:
                                        a_priori_estimates:
                                            lagrange_multiplier:      [^repeat(0;72)]
                                        smoothness_constraints:
                                            difference_order: 0
                                            lagrange_multiplier: 0.0

                    characteristic[3]: 
                                type: real_part_of_refractive_index_spectral_dependent
                                retrieved: true
                                mode[1]:
                                    initial_guess:                       #1         #2        #3        #4        #5        #6       
                                        value:                        [^repeat(1.53;7)]
                                        min:                          [^repeat(1.33;7)]
                                        max:                          [^repeat(1.6;7)]
                                        index_of_wavelength_involved: [^repeat(0;7)]
                                    single_pixel:
                                        smoothness_constraints:
                                            difference_order: 1
                                            lagrange_multiplier: 1.0e+1
                                    multi_pixel:
                                        smoothness_constraints:
                                            derivative_order_of_X_variability:    1
                                            lagrange_multiplier_of_X_variability: 1.0e-1                        
                                            derivative_order_of_Y_variability:    1
                                            lagrange_multiplier_of_Y_variability: 1.0e-1                     
                                            derivative_order_of_T_variability:    1
                                            lagrange_multiplier_of_T_variability: 2.0e-2                                               
                                mode[2]:
                                    initial_guess:                       #1         #2        #3        #4        #5        #6       
                                        value:                        [^repeat(1.53;7)]
                                        min:                          [^repeat(1.33;7)]
                                        max:                          [^repeat(1.6;7)]
                                        index_of_wavelength_involved: [^repeat(0;7)]
                                    single_pixel:
                                        smoothness_constraints:
                                            difference_order: 1
                                            lagrange_multiplier: 1.0e+1
                                    multi_pixel:
                                        smoothness_constraints:
                                            derivative_order_of_X_variability:    1
                                            lagrange_multiplier_of_X_variability: 1.0e-1                        
                                            derivative_order_of_Y_variability:    1
                                            lagrange_multiplier_of_Y_variability: 1.0e-1                     
                                            derivative_order_of_T_variability:    1
                                            lagrange_multiplier_of_T_variability: 2.0e-2                                               
                                mode[3]:
                                    initial_guess:                       #1         #2        #3        #4        #5        #6       
                                        value:                        [^repeat(1.53;7)]
                                        min:                          [^repeat(1.33;7)]
                                        max:                          [^repeat(1.6;7)]
                                        index_of_wavelength_involved: [^repeat(0;7)]
                                    single_pixel:
                                        smoothness_constraints:
                                            difference_order: 1
                                            lagrange_multiplier: 1.0e+1
                                    multi_pixel:
                                        smoothness_constraints:
                                            derivative_order_of_X_variability:    1
                                            lagrange_multiplier_of_X_variability: 1.0e-1                        
                                            derivative_order_of_Y_variability:    1
                                            lagrange_multiplier_of_Y_variability: 1.0e-1                     
                                            derivative_order_of_T_variability:    1
                                            lagrange_multiplier_of_T_variability: 2.0e-2       

                                .
                                .
                                .