Merge pull request #235 from ludwig-cf/develop

Release v0.19.0

.github/workflows/codeql-analysis.yml

@@ -32,15 +32,15 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        language: [ 'cpp', 'python' ]
+        language: [ 'cpp' ]
 
     steps:
     - name: Checkout repository
       uses: actions/checkout@v2
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
+      uses: github/codeql-action/init@v2
       with:
         languages: ${{ matrix.language }}
         queries: +security-and-quality
@@ -53,4 +53,4 @@ jobs:
        make
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v2

CHANGES.md

@@ -1,6 +1,34 @@
 
 ### Changes
 
+version 0.19.0
+
+- There has been a significant change to the way that i/o is undertaken.
+  See https://ludwig.epcc.ed.ac.uk/outputs/fluid.html
+  It is the intension to replace completely the 'old' I/O mechanism
+  by release v0.21.0.
+- The extract_colloids.c utility has been updated so that it takes
+  only one comand line argument for new I/O metadata.
+
+- Input associated with the choice of force arising from the free energy
+  sector has been made more general. Specifically, input keys
+  `fd_force_divergence` and `fe_use_stress_relaxation` are replaced.
+  - For scalar order parameters an extra version of the "phi_gradmu"
+    approach is avaialble" "phi_gradmu_correction".
+  - See https://ludwig.epcc.ed.ac.uk/inputs/force.html for details.
+- Order parameter statistics are now reported as "phi" for scalars
+  [Px,Py,Pz] for vectors, and [Qxx, Qxy, Qxz, Qyy, Qyz] for liquid
+  crystal. The computation of the total has been improved by using a
+  compensated sum, which is more robust to threads/MPI.
+- Added compiler option information and git commit information at run
+  time.
+- The LaTeX tutorials document has been replaced by html tutorials
+  at https://ludwig.epcc.ed.ac.uk/ to reflect new I/O and to add a
+  number of new topics.
+- LTGM.com analysis has been retired as the service has closed. The
+  two outstanding recommendations are covered by CodeQL notes.
+- Various minor updates.
+
 version 0.18.0
 
 - Added a lubrication correction offset to allow an option for keeping

CONTRIBUTING.md

@@ -10,6 +10,9 @@ Computing Centre. However, contributions are welcome.
 
 The code is released under a BSD 3-clause license.
 
+Please note that a contribution means signing over copyright to
+The University of Edinburgh.
+
 ### Running the tests
 
 Various tests exist in the `test` subdirectory. To check that no
@@ -83,3 +86,82 @@ $ git branch -d patch-0.1.2
 
 Release branches must branch from develop and must be merged back into both
 develop and master.
+
+
+### Code quality
+
+One hesitates before making pronouncements on style, but here goes
+anyway. As with English, the aim is not to follow rules, the aim to
+be clear and unambiguous.
+
+#### Notes on style
+
+The code has historically been ANSI C, but the advent of GPUs has
+meant that the C is a subset of ANSI which is also C++. This means
+there are a few things which are legal in ANSI C, but need to be
+avoided in the C++ context.
+
+- Avoid C++ reserved words as variable names. E.g.,
+  ```
+  int new = 0;
+  ```
+
+- Explicit casts are required in some situations to satisfy C++. A common
+  example is
+  ```
+  double * p = NULL;
+  p = (double *) malloc(...); /* Requires the cast in C++ */
+  ```
+
+- Don't be tempted by variable-sized object initialisation, e.g.,
+  ```
+  int nbyte = 2;
+  char tmp[nbyte+1] = {0}; /* variable sized initialisation */
+  ```
+  must be replaced by
+  ```
+  int nbyte = 2;
+  char tmp[2+1] = {0};
+  ```
+  or some equivalent compile-time constant expression. ANSI does not
+  allow variable-sized initialisation.
+
+Finally, note we use C-style comments `/* ... */` and not C++
+single line comments as a matter of stubborn consistency.
+
+
+#### Avoiding CodeQL alerts
+
+While some existing alerts remain, the goal is zero alerts. No new alerts
+should be added if at all possible.
+
+- CodeQL failures at severity "High" and above will prevent merges.
+  They need to be fixed.
+
+- Use `util_fopen()` from `util_fopen.h` in place of `fopen()`. This
+  will avoid `File created without restricting permissions` errors.
+
+- Some care can be required with integer types, e.g., something like
+  ```
+  {
+    int b = ...;
+    int c = ...;
+    size_t a = c*(b+1)*sizeof(double);
+  }
+  ```
+  will generate a `Multiplication result converted to larger type`.
+  One needs to have the multiplication before the conversion.
+  ```
+    {
+    int b = ...;
+    int c = ...;
+    int d = c*(b+1);
+    size_t a = d*sizeof(double);
+  }
+```
+If `c*(b+1)` may overflow, then an explicit cast to `size_t`is required.
+
+- Anything using `scanf()` and the like must check return values.
+
+- Try to use fixed `const char *` strings where possible, as the
+  alternative of character buffers is a good source of problems.

README.md

@@ -72,13 +72,16 @@ See `CONTRIBUTING.md` for further details of testing and
 development.
 
 
-#### Attribution
+#### Credits
 
 [![DOI](https://zenodo.org/badge/137508275.svg)](https://zenodo.org/badge/latestdoi/137508275)
 
 Recent release versions have a Zenodo-provided DOI. Please consider using the
 appropriate DOI as a reference if you use Ludwig in your publications.
 
+From Version 0.19.0 we have included a copy of `cJSON` which is released
+under an MIT license by Gave Gamble at https://github.com/DaveGamble/cJSON.
+
 #### Help
 
 

docs/tutorial/colloid-test1/colloid-test1.inp

@@ -0,0 +1,100 @@
+##############################################################################
+#
+#  Colloid simple configuration output
+#
+##############################################################################
+
+N_start  0
+N_cycles 1000
+
+##############################################################################
+#
+#  System and MPI
+# 
+##############################################################################
+
+size        32_32_32
+periodicity 1_1_1
+
+##############################################################################
+#
+#  Fluid parameters
+#
+##############################################################################
+
+viscosity 0.1
+
+isothermal_fluctuations   on
+temperature               0.000001
+
+##############################################################################
+#
+#  Free energy parameters
+#
+###############################################################################
+
+free_energy  none
+
+###############################################################################
+#
+#  Colloid parameters
+#
+###############################################################################
+
+colloid_init        input_random
+
+colloid_random_a0   2.30
+colloid_random_ah   2.30
+colloid_random_no   10
+colloid_random_dh   1.0
+
+###############################################################################
+#
+# Colloid-colloid soft-sphere potential parameters
+# The soft sphere is always needed
+#
+###############################################################################
+
+soft_sphere_on        1
+soft_sphere_epsilon   0.0004
+soft_sphere_sigma     0.1
+soft_sphere_nu        1.0
+soft_sphere_cutoff    0.25
+
+###############################################################################
+#
+#  Walls / boundaries
+#
+###############################################################################
+
+boundary_walls 0_0_0
+
+###############################################################################
+#
+#  Output frequency and type
+#
+###############################################################################
+
+default_io_mode   mpiio
+
+freq_statistics   250
+config_at_end     yes
+
+##############################################################################
+#
+#  colloid i/o
+#
+##############################################################################
+
+colloid_io_freq          1000
+colloid_io_format_output ASCII
+
+###############################################################################
+#
+#  Miscellaneous
+#
+#  random_seed  +ve integer is the random number generator seed
+#
+###############################################################################
+
+random_seed 8361435