newfluxdata.rst 5.78 KB
Newer Older
1
####################################################################################
2
How to add a new type of flux data to be processed by the CIF into a model's inputs
3
####################################################################################
4
5
6
7

.. role:: bash(code)
   :language: bash

8
9
Pre-requisites
================
10

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
Before starting to implement a new flux plugin, you must have:

    - a yaml file ready with a simulation that works with known plugins.
    - a folder where the data you need to implement is stored
    - basic information about the data you need to implement (licensing, format, etc.)

We help you below to navigate through different documentation pages to implement your plugin.
The main reference pages are :doc:`the datastream documentation page </documentation/plugins/datastreams/index>`
and :doc:`the flux template documentation page</documentation/plugins/datastreams/fluxes/flux_plugin_template>`.

Switch from working fluxes to the reference template
=====================================================

The :bash:`datavect` paragraph of your working yaml should look like that:

.. container:: toggle

  .. container:: header

     Show/Hide Code

  .. code-block:: yaml
    :linenos:

    datavect:
      plugin:
        name: standard
        version: std
      components:
        flux:
          parameters:
            CO2:
              plugin:
                name: CHIMERE
                type: flux
                version: AEMISSIONS
              file_freq: 120H
              dir: some_dir
              file: some_file


  1. follow the initial steps in :doc:`the flux template documentation page</documentation/plugins/datastreams/fluxes/flux_plugin_template>`
     to initialize your new plugin and register it.

     It includes copying the template folder to a new path and changing the variables
     :bash:`_name`,:bash:`_fullname` and :bash:`_version` in the file :bash:`__init__.py`

  2. update your Yaml to use the template flux (renamed with your preference). It should now look like that:

     .. container:: toggle

       .. container:: header

         Show/Hide Code

       .. code-block:: yaml
         :linenos:

           datavect:
             plugin:
               name: standard
               version: std
             components:
               flux:
                 parameters:
                   CO2:
                     plugin:
                       name: your_new_name
                       type: flux
                       version: your_version

Antoine Berchet's avatar
Antoine Berchet committed
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
  3. Test running again your test case. It should generate fluxes with random values as in the template

Document your plugin
====================

Before going further, be sure to document your plugin properly.

To do so, please replace the docstring header in the file :bash:`__init__.py`.

Include the following information:

    - licensing information
    - permanent link to download the data (or a contact person if no link is publicly available)
    - data format (temporal and horizontal resolution, names and shape of the data files)
    - any specific treatment that prevents the plugin from working with another type of files.


Updating functions and data to implement your flux data
=======================================================



104
105
106
107



#####################################
108

109
110
111



112
  0. .. include:: ../newBCdata/knownplugin.rst
113

114

115
116
  1. In directory :bash:`plugins/fluxes`, copy the directory containing the template
     for a flux plugin :bash:`flux_plugin_template` in the directory for your new plugin.
117

118
     .. include:: ../newBCdata/register.rst
119

120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

  2. Modify the yaml file to use the new plugin: the minimum input arguments are
     :bash:`dir`, :bash:`file`, :bash:`varname` and :bash:`unit_conversion`.
     The default space and time interpolations will be applied
     (see XXXX doc sur premiere simu directe avec exmeple yaml quand mise a jourXXXXX).

     .. code-block:: yaml

       components:
         fluxes:
           plugin:
              name: fluxes
              version: template
              type: fluxes
           dir: dir_with_original_files/
           file: file_with_new_fluxes_to_use_as_inputs
           varname: NAMEORIG
           unit_conversion:
                 scale: 1.

  3. .. include:: ../newBCdata/devplugin.rst

     XXXXXXX what about the input arguements? Ils demandent une partie dediee!?XXXXXXXXXX
143

144
4. Document the new plugin:
145
   
146
147
148
   a) .. include:: ../newBCdata/readme.rst 


Antoine Berchet's avatar
Antoine Berchet committed
149
   b) create the rst file that contains the automatic documentation in  docs/source/documentation/plugins/fluxes/. Please provide it with a self-explaining name. Example for the template: file fluxes_template.rst reads
150
151
152
153
154
155
156
157
158
159

     .. code-block:: rest

       .. role:: bash(code)
          :language: bash

       ###########################
       Template plugin for fluxes
       ###########################

160
       .. automodule:: pycif.plugins.datastreams.fluxes.flux_plugin_template
161

Antoine Berchet's avatar
Antoine Berchet committed
162
   c) add the reference to the rst file in docs/source/documentation/plugins/fluxes/index.rst:
163
164
165

     .. code-block:: rest

Antoine Berchet's avatar
Antoine Berchet committed
166
        #####################
167
        Fluxes :bash:`fluxes`
Antoine Berchet's avatar
Antoine Berchet committed
168
        #####################
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186

        Available Fluxes
        =========================

        The following :bash:`fluxes` are implemented in pyCIF:

        .. toctree::
             :maxdepth: 3
            
             fluxes_template
             dummy_nc
             dummy_txt
             edgar_v5
             flexpart
             chimere
             lmdz_bin
             lmdz_sflx

Antoine Berchet's avatar
Antoine Berchet committed
187
   d) built the documentation (:bash:`make html` in docs/) and check that the link to the new plugin appears in the documentation at file:///your_path/cif/docs/build/html/documentation/plugins/index.html and that the section "doc" of the input arguments is correctly displayed at file:///your_path/cif/docs/build/html/documentation/plugins/fluxes/the_new_plugin.html
188