Skip to content

contributing

Jump to bottom
Andrea Alfonsi - INL edited this page Apr 11, 2018 · 51 revisions

Bug and Development Reporting

If you are a user and:

  • if you have detected an anomalous behavior of RAVEN (a bug), or,
  • if you have the need of a new feature added to RAVEN

feel free to:

  • contact us using the RAVEN user mailing list (inl-raven-users@googlegroups.com)
  • create a new issue in the webpage: https://github.com/idaholab/raven/issues. If the issue is not assigned to a specific developer, please mention it to @alfoa @PaulTalbot-INL or @mandd in the issue description. If possible, include: input files, output files and version of the libraries so we can recreate and fix the issue more quickly.

External Contribution to RAVEN code

General Contribution Workflow

The contribution of external users/developer is welcome. In order to contribute to the RAVEN code, follow the steps below:

  • Open an ISSUE (here) explaining the development and/or feature
  • Create a branch in your own FORK of RAVEN
  • Perform the development
  • Open a Pull Request (here) and wait for a RAVEN developer to review it

It is important to notice that an external development will be accepted if:

  • The RAVEN team agrees that such development should be placed in RAVEN mainstream (wait for a developer to review your ISSUE before beginning the development).
  • If the development follows the RAVEN standards (e.g. coding standards, check lists, documentation). More information about development standards can be found here-dev_guide and here-check_lists.

New Code Interface

A typical external developers' contribution is represented by the coupling of RAVEN with an external Code. The procedure to couple a new code is detailed in:

  • the user manual, located in ./doc/user_manual/raven_user_manual.pdf, and
  • the workshop presentation that can be found in ./doc/workshop/codeCoupling/code_coupling.pptx.

Note: Only Code Interfaces that inherits from CodeInterfaceBase base class (i.e. class NewCodeInterface(CodeInterfaceBase)) will be accepted since the base class CodeInterfaceBase allows RAVEN to test the mechanics of the Interface without the need of an executable (see below).

Once the development of a new Code interface is finalized, two requirements need to be satisfied before the contribution can be pushed to RAVEN main repository:

  • User Manual Update
  • Addition of test cases In the following subsections, these two requirements are further discussed.

User Manual Update

The RAVEN user manual needs to be updated, adding a new chapter under the section Existing Interfaces explaining the usage of the new code interface. The new section must contain (at least) the following subsections:

  1. General Information: General description of the newly developed interface (e.g. usage, possible limitations, etc.)
  2. Models: Section explaining how to invoke the new code interface, with a clear description of all the possible additional XML nodes that the new code interface requires to be run correctly (e.g. special keywords, initialization options, etc.)
  3. Files: Section explaining which input files might be required and the way to list them. For example, allowed input files, input files' extensions, special types (e.g. input.inp )
  4. Samplers/Optimizers: Section explaining the syntax of the variables' naming conventions used to "inform" the code interface on how to perturb the input files (e.g. )
  5. Output Files conversion: Section explaining the way the output files of the driven code are converted into the RAVEN-compatible CSV file (e.g. variable naming conventions, types of outputs that are exported, etc.)

Addition of test cases

A set of tests (at least 1) to test the new code interface needs to be created. The tests need to cover all the mechanics present in the newly developed Code interface, such as:

  1. input parsing,
  2. output parsing and conversion into RAVEN-compatible CSV file and
  3. all possible options that Code interface allows (e.g. different calculation types of the driven code, different optional outputs, etc.).

The procedure to add a new test is as follows:

  • Navigate to directory ./raven/tests/framework/CodeInterfaceTests/
  • Create a new folder named as the name of the newly developed Code Interface (e.g. RELAP5 if the class of the code interface is named RELAP5 (class RELAP5(CodeInterfaceBase):)
  • Create a text file named tests in the just-created directory. In this file, the tests' specs are going to be inputted. An example and explanation of the most common parameters is reported in the image below:
[Tests]
 [./test_1]
  type = 'RavenFramework'
  input = 'raven_input_file.xml'
  output = 'path/to/output/out_1.out path/to/output/out_2.out'
  csv = 'path/to/ordered/csv/csv_1.csv path/to/ordered/csv/csv_2.csv'
  UnorderedCsv = 'path/to/unordered/csv/u_csv_1.csv path/to/unordered/csv/u_csv_2.csv'
  xml = 'path/to/ordered/xml/xml_1.xml path/to/ordered/csv/xml_2.xml'
  UnorderedXml = 'path/to/unordered/xml/u_xml_1.xml path/to/unordered/xml/u_xml_2.xml'
  text = 'path/to/a/text/file/a_text.inp path/to/a/text/file/a_text.out'
  max_time = 500
  rel_err = 1e-5
  test_interface_only = True 
 [../]
 [./test_2]
  ...
 [../]
 ...
[]

 In order to create a test for a Code interface (without the need to have an executable), the tag test_interface_only must be set to True. In addition, any file that needs to be "compered" with any of the DIFFER reported above needs to be placed in ```./raven/tests/framework/CodeInterfaceTests/NewInterfaceFolder/gold/path/to/output/file*``.

 The only difference between a test with or without the executable of the driven code is represented by the presence of the output in the working directory.  For example, assume that: * the test test_my_interface.xml is located in the directory ./raven/tests/framework/CodeInterfaceTests/Scale, * the (in test_my_interface.xml) is set to SCALE_triton``, * the <Step> is named sampleScaleand it generates 2 realizations (samples) of the driven model, whose outputs are namedtriton_dv1a.out&nbsp; the outputtriton_dv1a.outfor the first realization must be added in./raven/tests/framework/CodeInterfaceTests/Scale/Scale_triton/sampleScale/1/and for the second in./raven/tests/framework/CodeInterfaceTests/Scale/Scale_triton/sampleScale/2/```.   The image below graphically shows it.

Clone this wiki locally