contributing

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 ([email protected])
• 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:

• 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.)
• A set of tests (at least 1) to test the new code interface:
   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 allow (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 reported. An example and explaination of the most common parameters is reported in the image below: