From 6887a16fa13c9b29f8447c85bf36341c3b5b8917 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 24 Jan 2022 17:49:32 -0500 Subject: [PATCH] start add general code design doc. --- doc/src/Developer.rst | 1 + doc/src/Developer_cxx_vs_c_style.rst | 73 ++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) create mode 100644 doc/src/Developer_cxx_vs_c_style.rst diff --git a/doc/src/Developer.rst b/doc/src/Developer.rst index fd4a44a8a0..4d82f93625 100644 --- a/doc/src/Developer.rst +++ b/doc/src/Developer.rst @@ -11,6 +11,7 @@ of time and requests from the LAMMPS user community. :maxdepth: 1 Developer_org + Developer_cxx_vs_c_style Developer_parallel Developer_flow Developer_write diff --git a/doc/src/Developer_cxx_vs_c_style.rst b/doc/src/Developer_cxx_vs_c_style.rst new file mode 100644 index 0000000000..868b183ec0 --- /dev/null +++ b/doc/src/Developer_cxx_vs_c_style.rst @@ -0,0 +1,73 @@ +Code design +----------- + +This section discusses some of the code design choices in LAMMPS and +overall strategy in order to assist developers to write new code that +will fit well with the remaining code. Please see the section on +:doc:`Requirements for contributed code ` for more +specific recommendations and guidelines. Here the focus is on overall +strategy and discussion of some relevant C++ programming language +constructs. + +Historically, the basic design philosophy of the LAMMPS C++ code was +that of a "C with classes" style. The was motivated by the desire to +make it easier to modify LAMMPS for people without significant training +in C++ programming and by trying to use data structures and code constructs +that somewhat resemble the previous implementation(s) in Fortran. +A contributing factor for this choice also was that at the time the +implementation of C++ compilers was not always very mature and some of +the advanced features contained bugs or were not functioning exactly +as the standard required; plus there was some disagreement between +compiler vendors about how to interpret the C++ standard documents. + +However, C++ compilers have advanced a lot since then and with the +transition to requiring the C++11 standard in 2020 as the minimum C++ language +standard for LAMMPS, the decision was made to also replace some of the +C-style constructs with equivalent C++ functionality, either from the +C++ standard library or as custom classes or function, in order to +improve readability of the code and to increase code reuse through +abstraction of commonly used functionality. + + +Object oriented code +^^^^^^^^^^^^^^^^^^^^ + +LAMMPS is designed to be an object oriented code, that is each simulation +is represented by an instance of the LAMMPS class. When running in parallel, +of course, each MPI process will create such an instance. This can be seen +in the ``main.cpp`` file where the core steps of running a LAMMPS simulation +are the following 3 lines of code: + +.. code-block:: C++ + + LAMMPS *lammps = new LAMMPS(argc, argv, lammps_comm); + lammps->input->file(); + delete lammps; + +The first line creates a LAMMPS class instance and passes the command line arguments +and the global communicator to its constructor. The second line tells the LAMMPS +instance to process the input (either from standard input or the provided input file) +until the end. And the third line deletes that instance again. The remainder of +the main.cpp file are for error handling, MPI configuration and other special features. + +In the constructor of the LAMMPS class instance the basic LAMMPS class hierachy +is created as shown in :ref:`class-topology`. While processing the input further +class instances are created, or deleted, or replaced and specific member functions +of specific classes are called to trigger actions like creating atoms, computing +forces, computing properties, propagating the system, or writing output. + + +Inheritance and Compositing +=========================== + +Polymorphism +============ + + +I/O and output formatting +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Memory management +^^^^^^^^^^^^^^^^^ + +