Changeset 1182 for XIOS


Ignore:
Timestamp:
06/23/17 15:01:47 (7 years ago)
Author:
rlacroix
Message:

Update the documentation.

Document the "xios_field_is_active" function and the "check_if_active" field attribute.

Location:
XIOS/trunk/doc
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • XIOS/trunk/doc/XIOS_reference_guide.lyx

    r1084 r1182  
    34373437 
    34383438\begin_layout Subsection* 
     3439check_if_active:  
     3440\emph on 
     3441bool 
     3442\end_layout 
     3443 
     3444\begin_layout Standard 
     3445Fortran: 
     3446\end_layout 
     3447 
     3448\begin_layout LyX-Code 
     3449LOGICAL :: check_if_active 
     3450\end_layout 
     3451 
     3452\begin_layout Standard 
     3453Define whether XIOS will automatically check if the field is active at current 
     3454 timestep when sending data from the model. 
     3455 Enabling this behavior can sometimes improve the performances by avoiding 
     3456 unneeded data processing. 
     3457 This attribute is optional, the default value is  
     3458\begin_inset Flex Strong 
     3459status collapsed 
     3460 
     3461\begin_layout Plain Layout 
     3462false 
     3463\end_layout 
     3464 
     3465\end_inset 
     3466 
     3467. 
     3468\end_layout 
     3469 
     3470\begin_layout Subsection* 
    34393471field_ref:  
    34403472\emph on 

  • XIOS/trunk/doc/XIOS_user_guide.lyx

    r1084 r1182  
    188188\begin_layout Plain Layout 
    189189 
    190 ! Context initialization ommited, see the corresponding section of this 
     190! Context initialization omitted, see the corresponding section of this 
    191191 user manual and of the reference manual 
    192192\end_layout 
    … …  
    293293\begin_layout Plain Layout 
    294294 
    295 ! Context initialization ommited, see the corresponding section of this 
     295! Context initialization omitted, see the corresponding section of this 
    296296 user manual and of the reference manual 
    297297\end_layout 
    … …  
    476476\begin_layout Plain Layout 
    477477 
    478 ! Context initialization ommited, see the corresponding section of this 
     478! Context initialization omitted, see the corresponding section of this 
    479479 user manual and of the reference manual 
    480480\end_layout 
    … …  
    524524\begin_layout Plain Layout 
    525525 
    526 ! Context initialization ommited, see the corresponding section of this 
     526! Context initialization omitted, see the corresponding section of this 
    527527 user manual and of the reference manual 
    528528\end_layout 
    … …  
    788788\begin_layout Plain Layout 
    789789 
    790 ! Context initialization ommited, see the corresponding section of this 
     790! Context initialization omitted, see the corresponding section of this 
    791791 user manual and of the reference manual 
    792792\end_layout 
    … …  
    13301330\begin_layout Plain Layout 
    13311331 
    1332                         <!-- Content of the file ommited for now --> 
     1332                        <!-- Content of the file omitted for now --> 
    13331333\end_layout 
    13341334 
    … …  
    14281428\begin_layout Plain Layout 
    14291429 
    1430 ! Context and calendar initializations ommited, see the corresponding section 
     1430! Context and calendar initializations omitted, see the corresponding section 
    14311431 of this user manual and of the reference manual 
    14321432\end_layout 
    … …  
    19531953\begin_layout Plain Layout 
    19541954 
    1955                         <!-- Content of the file ommited for now --> 
     1955                        <!-- Content of the file omitted for now --> 
    19561956\end_layout 
    19571957 
    … …  
    21952195\begin_layout Plain Layout 
    21962196 
    2197                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     2197                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    21982198\end_layout 
    21992199 
    … …  
    24572457\begin_layout Plain Layout 
    24582458 
    2459 ! Context, calendar and grid initializations ommited, see the corresponding 
     2459! Context, calendar and grid initializations omitted, see the corresponding 
    24602460 section of this user manual and of the reference manual 
    24612461\end_layout 
    … …  
    27362736\begin_layout Plain Layout 
    27372737 
    2738                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     2738                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    27392739\end_layout 
    27402740 
    … …  
    31993199\begin_layout Plain Layout 
    32003200 
    3201                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     3201                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    32023202\end_layout 
    32033203 
    … …  
    33093309\begin_layout Plain Layout 
    33103310 
    3311                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     3311                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    33123312\end_layout 
    33133313 
    … …  
    34603460\begin_layout Plain Layout 
    34613461 
    3462                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     3462                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    34633463\end_layout 
    34643464 
    … …  
    36093609\begin_layout Plain Layout 
    36103610 
    3611                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     3611                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    36123612\end_layout 
    36133613 
    … …  
    38013801\begin_layout Plain Layout 
    38023802 
    3803                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     3803                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    38043804\end_layout 
    38053805 
    … …  
    39423942\begin_layout Plain Layout 
    39433943 
    3944                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     3944                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    39453945\end_layout 
    39463946 
    … …  
    40824082\begin_layout Plain Layout 
    40834083 
    4084                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     4084                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    40854085\end_layout 
    40864086 
    … …  
    42784278\begin_layout Plain Layout 
    42794279 
    4280                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     4280                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    42814281\end_layout 
    42824282 
    … …  
    44574457\begin_layout Plain Layout 
    44584458 
    4459                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     4459                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    44604460\end_layout 
    44614461 
    … …  
    45644564, the requested data will never be available and a deadlock could occur. 
    45654565 In practice, XIOS will detect the problem and throw an error. 
     4566\end_layout 
     4567 
     4568\begin_layout Section 
     4569How to check whether a field is active or not 
     4570\end_layout 
     4571 
     4572\begin_layout Standard 
     4573Since XIOS allows modifying the output and input files at runtime, it is 
     4574 sometimes useful to be able to dynamically query whether a field is active 
     4575 or not from the model (for example to avoid computing a field that would 
     4576 not be used anyway for the current run). 
     4577\begin_inset Newline newline 
     4578\end_inset 
     4579 
     4580 
     4581\begin_inset Newline newline 
     4582\end_inset 
     4583 
     4584This can be done using the  
     4585\begin_inset Flex Code 
     4586status open 
     4587 
     4588\begin_layout Plain Layout 
     4589xios_field_is_active 
     4590\end_layout 
     4591 
     4592\end_inset 
     4593 
     4594 function. 
     4595 The following code sample shows how this function could be used in a model: 
     4596\end_layout 
     4597 
     4598\begin_layout Standard 
     4599\begin_inset listings 
     4600lstparams "language=Fortran,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}" 
     4601inline false 
     4602status open 
     4603 
     4604\begin_layout Plain Layout 
     4605 
     4606IF (xios_field_is_active("field_A")) THEN 
     4607\end_layout 
     4608 
     4609\begin_layout Plain Layout 
     4610 
     4611        ! Computation of field_A 
     4612\end_layout 
     4613 
     4614\begin_layout Plain Layout 
     4615 
     4616        ! ... 
     4617\end_layout 
     4618 
     4619\begin_layout Plain Layout 
     4620 
     4621\end_layout 
     4622 
     4623\begin_layout Plain Layout 
     4624 
     4625        CALL xios_send_field("field_A", field_A) 
     4626\end_layout 
     4627 
     4628\begin_layout Plain Layout 
     4629 
     4630ENDIF 
     4631\end_layout 
     4632 
     4633\end_inset 
     4634 
     4635Note that this function takes into account the possible data dependencies 
     4636 that can exist between fields. 
     4637 That is, a field will be considered active if it used to compute another 
     4638 active field even if it is not directly used in any files. 
     4639\begin_inset Newline newline 
     4640\end_inset 
     4641 
     4642 
     4643\begin_inset Newline newline 
     4644\end_inset 
     4645 
     4646The  
     4647\begin_inset Flex Code 
     4648status open 
     4649 
     4650\begin_layout Plain Layout 
     4651xios_field_is_active 
     4652\end_layout 
     4653 
     4654\end_inset 
     4655 
     4656 function accepts an optional boolean argument  
     4657\begin_inset Flex Code 
     4658status open 
     4659 
     4660\begin_layout Plain Layout 
     4661at_current_timestep 
     4662\end_layout 
     4663 
     4664\end_inset 
     4665 
     4666 which defaults to  
     4667\series bold 
     4668false 
     4669\series default 
     4670 if omitted. 
     4671 Setting it to  
     4672\series bold 
     4673true 
     4674\series default 
     4675 allows checking if an input field is active at the current timestep, taking 
     4676 into account the data sampling and temporal operations. 
     4677\begin_inset Newline newline 
     4678\end_inset 
     4679 
     4680 
     4681\begin_inset Newline newline 
     4682\end_inset 
     4683 
     4684Considering the following configuration file: 
     4685\begin_inset listings 
     4686lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}" 
     4687inline false 
     4688status open 
     4689 
     4690\begin_layout Plain Layout 
     4691 
     4692<?xml version="1.0"?> 
     4693\end_layout 
     4694 
     4695\begin_layout Plain Layout 
     4696 
     4697<simulation> 
     4698\end_layout 
     4699 
     4700\begin_layout Plain Layout 
     4701 
     4702        <context id="test"> 
     4703\end_layout 
     4704 
     4705\begin_layout Plain Layout 
     4706 
     4707                <calendar type="Gregorian" timestep="1h" /> 
     4708\end_layout 
     4709 
     4710\begin_layout Plain Layout 
     4711 
     4712\end_layout 
     4713 
     4714\begin_layout Plain Layout 
     4715 
     4716                <grid_definition> 
     4717\end_layout 
     4718 
     4719\begin_layout Plain Layout 
     4720 
     4721                        <grid id="grid_A"><!-- Definition omitted --></grid> 
     4722\end_layout 
     4723 
     4724\begin_layout Plain Layout 
     4725 
     4726                </grid_definition> 
     4727\end_layout 
     4728 
     4729\begin_layout Plain Layout 
     4730 
     4731\end_layout 
     4732 
     4733\begin_layout Plain Layout 
     4734 
     4735                <field_definition> 
     4736\end_layout 
     4737 
     4738\begin_layout Plain Layout 
     4739 
     4740                <field id="field_A" grid_ref="grid_A" operation="instant" /> 
     4741\end_layout 
     4742 
     4743\begin_layout Plain Layout 
     4744 
     4745                <field id="field_B" grid_ref="grid_A" operation="instant" /> 
     4746\end_layout 
     4747 
     4748\begin_layout Plain Layout 
     4749 
     4750                <field id="field_C" grid_ref="grid_A" operation="instant">field_A 
     4751 + field_B</field> 
     4752\end_layout 
     4753 
     4754\begin_layout Plain Layout 
     4755 
     4756                </field_definition> 
     4757\end_layout 
     4758 
     4759\begin_layout Plain Layout 
     4760 
     4761\end_layout 
     4762 
     4763\begin_layout Plain Layout 
     4764 
     4765                <file_definition> 
     4766\end_layout 
     4767 
     4768\begin_layout Plain Layout 
     4769 
     4770                        <file name="output" output_freq="10ts"> 
     4771\end_layout 
     4772 
     4773\begin_layout Plain Layout 
     4774 
     4775                        <field field_ref="field_C" /> 
     4776\end_layout 
     4777 
     4778\begin_layout Plain Layout 
     4779 
     4780                        </file> 
     4781\end_layout 
     4782 
     4783\begin_layout Plain Layout 
     4784 
     4785                </file_definition> 
     4786\end_layout 
     4787 
     4788\begin_layout Plain Layout 
     4789 
     4790        </context> 
     4791\end_layout 
     4792 
     4793\begin_layout Plain Layout 
     4794 
     4795</simulation> 
     4796\end_layout 
     4797 
     4798\end_inset 
     4799 
     4800With this configuration file, calling  
     4801\begin_inset Flex Code 
     4802status open 
     4803 
     4804\begin_layout Plain Layout 
     4805xios_field_is_active( 
     4806\begin_inset Quotes eld 
     4807\end_inset 
     4808 
     4809field_A 
     4810\begin_inset Quotes erd 
     4811\end_inset 
     4812 
     4813) 
     4814\end_layout 
     4815 
     4816\end_inset 
     4817 
     4818 or 
     4819\begin_inset Newline newline 
     4820\end_inset 
     4821 
     4822 
     4823\begin_inset Flex Code 
     4824status open 
     4825 
     4826\begin_layout Plain Layout 
     4827xios_field_is_active( 
     4828\begin_inset Quotes eld 
     4829\end_inset 
     4830 
     4831field_B 
     4832\begin_inset Quotes erd 
     4833\end_inset 
     4834 
     4835) 
     4836\end_layout 
     4837 
     4838\end_inset 
     4839 
     4840 always returns  
     4841\series bold 
     4842true 
     4843\series default 
     4844 because  
     4845\begin_inset Quotes eld 
     4846\end_inset 
     4847 
     4848field_A 
     4849\begin_inset Quotes erd 
     4850\end_inset 
     4851 
     4852 and  
     4853\begin_inset Quotes eld 
     4854\end_inset 
     4855 
     4856field_B 
     4857\begin_inset Quotes erd 
     4858\end_inset 
     4859 
     4860 are needed to compute  
     4861\begin_inset Quotes eld 
     4862\end_inset 
     4863 
     4864field_C 
     4865\begin_inset Quotes erd 
     4866\end_inset 
     4867 
     4868 which is outputted. 
     4869 Since  
     4870\begin_inset Quotes eld 
     4871\end_inset 
     4872 
     4873field_C 
     4874\begin_inset Quotes erd 
     4875\end_inset 
     4876 
     4877 is outputted every 10 timesteps, setting the  
     4878\begin_inset Flex Code 
     4879status open 
     4880 
     4881\begin_layout Plain Layout 
     4882at_current_timestep 
     4883\end_layout 
     4884 
     4885\end_inset 
     4886 
     4887 argument to  
     4888\series bold 
     4889true 
     4890\series default 
     4891 would make a difference. 
     4892 Calling  
     4893\begin_inset Flex Code 
     4894status open 
     4895 
     4896\begin_layout Plain Layout 
     4897xios_field_is_active( 
     4898\begin_inset Quotes eld 
     4899\end_inset 
     4900 
     4901field_A 
     4902\begin_inset Quotes erd 
     4903\end_inset 
     4904 
     4905, .true.) 
     4906\end_layout 
     4907 
     4908\end_inset 
     4909 
     4910 would return  
     4911\series bold 
     4912true 
     4913\series default 
     4914 only every 10 timesteps as there is no need to provide  
     4915\begin_inset Quotes eld 
     4916\end_inset 
     4917 
     4918field_A 
     4919\begin_inset Quotes erd 
     4920\end_inset 
     4921 
     4922 (respectively  
     4923\begin_inset Quotes eld 
     4924\end_inset 
     4925 
     4926field_B 
     4927\begin_inset Quotes erd 
     4928\end_inset 
     4929 
     4930) at timesteps for which  
     4931\begin_inset Quotes eld 
     4932\end_inset 
     4933 
     4934field_C 
     4935\begin_inset Quotes erd 
     4936\end_inset 
     4937 
     4938 is not written to file. 
     4939\begin_inset Newline newline 
     4940\end_inset 
     4941 
     4942 
     4943\begin_inset Newline newline 
     4944\end_inset 
     4945 
     4946Additionally, it possible to set the field attribute  
     4947\series bold 
     4948check_if_active 
     4949\series default 
     4950 to  
     4951\begin_inset Quotes eld 
     4952\end_inset 
     4953 
     4954 
     4955\series bold 
     4956\emph on 
     4957true 
     4958\series default 
     4959\emph default 
     4960 
     4961\begin_inset Quotes erd 
     4962\end_inset 
     4963 
     4964 so that XIOS internally check if a field is active before sending any data. 
     4965 For example, defining the following field: 
     4966\end_layout 
     4967 
     4968\begin_layout Standard 
     4969\begin_inset listings 
     4970lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}" 
     4971inline false 
     4972status open 
     4973 
     4974\begin_layout Plain Layout 
     4975 
     4976<field_definition> 
     4977\end_layout 
     4978 
     4979\begin_layout Plain Layout 
     4980 
     4981        <field id="field_A" grid_ref="grid_A" operation="instant" check_if_active 
     4982\series bold 
     4983="true" 
     4984\series default 
     4985 /> 
     4986\end_layout 
     4987 
     4988\begin_layout Plain Layout 
     4989 
     4990</field_definition> 
     4991\end_layout 
     4992 
     4993\end_inset 
     4994 
     4995has the same effect as if all calls to  
     4996\begin_inset Flex Code 
     4997status open 
     4998 
     4999\begin_layout Plain Layout 
     5000xios_send_field("field_A", field_A) 
     5001\end_layout 
     5002 
     5003\end_inset 
     5004 
     5005 were replaced by: 
     5006\end_layout 
     5007 
     5008\begin_layout Standard 
     5009\begin_inset listings 
     5010lstparams "language=XML,breaklines=true,tabsize=2,frame=tb,postbreak={\raisebox{0ex}[0ex][0ex]{\ensuremath{\rcurvearrowse\space}}}" 
     5011inline false 
     5012status open 
     5013 
     5014\begin_layout Plain Layout 
     5015 
     5016IF (xios_field_is_active("field_A"), .true.) THEN 
     5017\end_layout 
     5018 
     5019\begin_layout Plain Layout 
     5020 
     5021        CALL xios_send_field("field_A", field_A) 
     5022\end_layout 
     5023 
     5024\begin_layout Plain Layout 
     5025 
     5026ENDIF 
     5027\end_layout 
     5028 
     5029\end_inset 
     5030 
     5031 
    45665032\end_layout 
    45675033 
    … …  
    46615127\begin_layout Plain Layout 
    46625128 
    4663                         <grid id="grid_A"><!-- Definition ommited --></grid> 
     5129                        <grid id="grid_A"><!-- Definition omitted --></grid> 
    46645130\end_layout 
    46655131 
    … …  
    48765342\begin_layout Plain Layout 
    48775343 
    4878         <!-- Actual context(s) used by the simulation ommited --> 
     5344        <!-- Actual context(s) used by the simulation omitted --> 
    48795345\end_layout 
    48805346 
Note: See TracChangeset for help on using the changeset viewer.