newfluxdata.rst 5.13 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
82
83
84
85
86
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

  3. Test running again your test case. It should generate fluxes with random values



#####################################
87

88
89
90



91
  0. .. include:: ../newBCdata/knownplugin.rst
92

93

94
95
  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.
96

97
     .. include:: ../newBCdata/register.rst
98

99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

  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
122

123
4. Document the new plugin:
124
   
125
126
127
   a) .. include:: ../newBCdata/readme.rst 


Antoine Berchet's avatar
Antoine Berchet committed
128
   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
129
130
131
132
133
134
135
136
137
138

     .. code-block:: rest

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

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

139
       .. automodule:: pycif.plugins.datastreams.fluxes.flux_plugin_template
140

Antoine Berchet's avatar
Antoine Berchet committed
141
   c) add the reference to the rst file in docs/source/documentation/plugins/fluxes/index.rst:
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

     .. code-block:: rest

        ####################
        Fluxes :bash:`fluxes`
        ####################

        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
166
   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
167