diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d182944d99..b8322ce3e9 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,6 +6,7 @@ I confirm that I have completed the following checks: +- [ ] My changes follow the [PROCESS style guide](https://ukaea.github.io/PROCESS/development/standards/) - [ ] I have justified any large differences in the regression tests caused by this pull request in the comments. - [ ] I have added new tests where appropriate for the changes I have made. - [ ] If I have had to change any existing unit or integration tests, I have justified this change in the pull request comments. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb00434012..2e083d5ee3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ Please discuss any feature ideas you have with the developers before submitting * Submit an issue (if one does not exist for this feature/ bug) that documents the proposed change. * Fork our repository. * Create a branch off `main` with an appropriate name (e.g. `feature-abc`). -* Make the relevant changes for the repository (ensuring the changes do not creep away from the scope of the issue). +* Make the relevant changes for the repository (ensuring the changes do not creep away from the scope of the issue). Also ensure that the implementation follows the PROCESS [style guide](https://ukaea.github.io/PROCESS/development/standards/) for names of variables and functions etc. * Discuss any problems or development choices in the issue and keep everyone updated on the progress of your development. * If the changes are notable and it would benefit other users to be aware, [create a changelog entry](https://ukaea.github.io/PROCESS/development/versioning/). * Finally, submit a pull request onto the `main` branch: @@ -35,4 +35,5 @@ Please remember that all contributions are made under the [MIT license](https:// ### Testing PROCESS has unit, integration, and regression tests. Any new functionality must be appropriately tested. Sometimes, changes may require other tests to be changed. These changes should be justified in the pull request description. Tests can be run locally by following [our testing documentation](https://ukaea.github.io/PROCESS/development/testing/). All pull requests will also be run against our GitHub actions which will run all of the tests and report back to the reviewer any failures. **The unit and integration tests must pass on the CI for the changes to be accepted**. -Regression tests, due to the nature of PROCESS, can change as model changes affect the optima which PROCESS converges to. A reviewer will review these changes to ensure they are minor and justified. We recommend justifying how a regression test is changing in the pull request discussion, a reviewer will likely request this anyway. For convenience, the CI system runs a 0% tolerance job that will highlight all differences between the current version of PROCESS on the `main` branch and your modified version of PROCESS; the 5% job excludes all differences under 5% differences between the two versions. \ No newline at end of file +Regression tests, due to the nature of PROCESS, can change as model changes affect the optima which PROCESS converges to. A reviewer will review these changes to ensure they are minor and justified. We recommend justifying how a regression test is changing in the pull request discussion, a reviewer will likely request this anyway. For convenience, the CI system runs a 0% tolerance job that will highlight all differences between the current version of PROCESS on the `main` branch and your modified version of PROCESS; the 5% job excludes all differences under 5% differences between the two versions. + diff --git a/documentation/proc-pages/development/standards.md b/documentation/proc-pages/development/standards.md index d2de731716..5cbad1f700 100644 --- a/documentation/proc-pages/development/standards.md +++ b/documentation/proc-pages/development/standards.md @@ -1,10 +1,14 @@ # Style Guide +`PROCESS` follows the Python [PEP8](https://peps.python.org/pep-0008/) style guide for its layout and namespace style. This should not conflict with Fortran90 in terms of names but may with the line lengths. + +-------------------- + ## Line Length -For optimal readability, a limit of 100 characters for maximum line length has been set. This is -below the maximum line length of 132 characters for Fortran (to prevent compilation errors) and -prevents long lines that run on past the edge of the screen wasting programmers time with scrolling. +For optimal readability, a limit of 79 characters for maximum line length has been encouraged, as recommended in [PEP8](https://peps.python.org/pep-0008/). This is below the maximum line length of 132 characters for Fortran (to prevent compilation errors) and prevents long lines that run on past the edge of the screen wasting programmers time with scrolling. + +-------------------- ## Double declarations @@ -20,16 +24,49 @@ real(dp) :: b ``` +all new models should have their own function + +-------------------- + ## Naming conventions +!!! quote "The Zen of Python" + + *“Explicit is better than implicit.”* + + *"Readability counts."* + +### Functions + +Use a lowercase word or words. Separate words by underscores(`_`) to improve readability. + +### Switches + +Switches should start with the `i_` prefix in their name, be of integer type and should be indexed from 0. + +### Constants -### Case +Use an uppercase single letter, word, or words. Separate words with underscores to improve readability. -All variables should be lower case. +Refrain from declaring or typing known numerical constants directly in the code. Instead call the value from `constants.f90` +If the constants doesn't exist then add it with a source link and uncertainty value. + +### Variables + +Use a lowercase single letter, word, or words. Separate words with underscores to improve readability. +If converting between units it may be required to have some capital letters at the end of the variable name to differentiate between different orders of magnitude, `m` and `M` etc. + +#### Variables representing fractions + +If a variable is intended to demonstrate a fraction of a value or distribution etc. Then it should start with the `f_` prefix. + +#### F-values + +Variables used within constraint equations to scale iteration variables (f-values) should start with the `f` prefix without an underscore before the next word. ### Length -Try to keep variable names to a sensible length. Abbreviations of some parts of the name are suitable e.g. div for divertor. Use underscores to separate words. +Try to keep names to a sensible length while also keeping the name explicit and descriptive. ### Physical Type @@ -45,16 +82,18 @@ Another example would be pulse length time_pulse_length = 7200.0 ``` +------------------ + ### Units Inside PROCESS all variables should be in SI units unless otherwise stated. For example: ```fortran ! Fusion power [W] -p_fusion = 1000.0d6 +fusion_power = 1000.0d6 ! Fusion power [MW] -p_fusion_mw = 1000.0d0 +fusion_power_MW = 1000.0d0 ``` ### Coordinates and dimensions @@ -94,32 +133,114 @@ ii | Variable name | Description | Units | | ------------- | ----------- | :---: | -| `i_plasma` | Plasma current | A | -| `i_plasma_ma` | Plasma current | MA | +| `plasma_current` | Plasma current | A | +| `plasma_current_MA` | Plasma current | MA | | `b_t_onaxis` | Toroidal field on-axis | T | | `b_t_max` | Max toroidal field | T | | `n_electron_vol` | Volume average electron density | m-3 | | `t_electron_vol_ev` | Volume avgerage electron temperature | eV | -| `m_steel` | Mass of steel | kg | -| `m_steel_tonne` | Mass of steel | tonne | +| `mass_steel` | Mass of steel | kg | +| `mass_steel_tonne` | Mass of steel | tonne | | `e_neutron_ev` | Energy of neutron | eV | -| `e_neutron_mev` | Energy of neutron | MeV | +| `e_neutron_MeV` | Energy of neutron | MeV | | `v_tf_dump` | TF dump voltage | V | | `time_plant_life` | Plant lifetime | s | | `time_plant_life_yrs` | Plant lifetime | years | | `dr_tf_inboard_leg` | TF coil inboard leg radial thickness | m | | `dr_blanket_inboard` | Inboard blanket thickness | m | | `velocity_coolant` | TF centrepost coolant velocity | m/s | -| `vol_plasma` | Plasma volume | m3 | -| `a_plasma` | Plasma area | m2 | +| `plasma_volume` | Plasma volume | m3 | +| `plasma_area` | Plasma area | m2 | | `angle_div_target` | Divertor target angle | radians | | `angle_div_target_deg` | Divertor target angle | deg | | `sig_tf_r` | TF radial stress | Pa | | `` | | | -Please see issue 940 to discuss new conventions. +Please see issue [#940](https://github.com/ukaea/PROCESS/issues/940) to discuss new conventions. + +## Type-Hints + +It is greatly encouraged and recommended to include type hints for all inputs and outputs in Python. Please follow the guidelines set out in [PEP-484](https://peps.python.org/pep-0484/). + +## Docstrings + +The docstring style is that of the [Sphinx type](https://www.sphinx-doc.org/en/master/index.html). Though there are some additions for `Notes` and `References` in order to give mathematical reasoning and sources to some functions. + +### Functions + +If writing in new Python functions please use the docstring template below. + +```python +def function_name(param1, param2): + """ + Brief description of what the function does. + + Detailed description of the function. This can include information about the algorithm, + any important notes, and other relevant details. + + :param type param1: Description of the first parameter. + :param type param2: Description of the second parameter. + :returns: Description of the return value. + :rtype: return_type + :raises ExceptionType: Description of the exception raised (if any). + + :notes: + - Additional notes about the function. + - Any important considerations or caveats. + + :references: + - Reference 1: Description of the reference. + - Reference 2: Description of the reference. + """ +``` + +### Classes + +If writing in new Python classes please use the docstring template below. + +```python +class ExampleClass: + """ + Brief description of the class. + + Detailed description of the class. This can include information about the purpose + of the class, how it should be used, and any other relevant details. + + Attributes: + attribute1 (type): Description of attribute1. + attribute2 (type): Description of attribute2. + attribute3 (type): Description of attribute3. + + Methods: + method1(param1, param2): Description of method1. + method2(param1, param2): Description of method2. + """ + + def __init__(self, attribute1, attribute2, attribute3): + """ + Initializes the ExampleClass with the given attributes. + + :param type attribute1: Description of attribute1. + :param type attribute2: Description of attribute2. + :param type attribute3: Description of attribute3. + """ + self.attribute1 = attribute1 + self.attribute2 = attribute2 + self.attribute3 = attribute3 +``` + +## Comments + +- **Comments that contradict the code are worse than no comments** + +- Comments should be complete sentences. The first word should be capitalized, unless it is an identifier that begins with a lower case letter. + +- Use inline comments sparingly. + +- Comments above apply to code below. + -# Code Documentation Using FORD +## Code Documentation Using FORD PROCESS uses FORD (FORtran Documentation) to automatically generate documentation from comments in the FORTRAN code. FORD parses FORTRAN source to understand the structure of the project as well @@ -161,7 +282,7 @@ use "!!" for consistency. The rationale behind this and further information is i The FORD project on github can be found [here](https://github.com/Fortran-FOSS-Programmers/ford). -## Example of FORD documentation for a subroutine (constraint equation) +### Example of FORD documentation for a subroutine (constraint equation) ```fortran diff --git a/mkdocs.yml b/mkdocs.yml index 5658112ef1..4ddb8a4395 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,7 +38,7 @@ nav: - Standards: development/standards.md - F2Py Standards: development/f2py-standards.md # - Versioning: development/versioning.md - - Reference: + - Models: - Physics Models: - Plasma: - Overview: physics-models/plasma_overview.md