Topic: Modularity on documentation and input record fields

As we discussed in Prague, keeping the documentation up-to-date with input record fields is quite tedious.
Being able to keep all the information collected in one place would definitely improve the situation.
Also, efforts in writing pre-processors is also difficult. Most likely current approaches would be limited to a few selected elements and would break easily.

Keeping all the information in the source files would be the best place and would most likely ensure that the information is up-to-date.

For documentation:
Things are a bit simpler than for pre-processors here. We could possible write a small python script that would collect special syntax doxygen comments and place them in one place. This could be something like extending the current #define-block for input records. For example, it might look something like this

/**
  * @name BoundaryCondition
  * @group Boundary conditions
  * @ref GeneralBoundaryCondition
  * The Dirichlet type boundary condition directly enforces values of the primary fields. Can be applied to any type of set.
  */
//@{
#define _IFT_BoundaryCondition_Name "boundarycondition"
#define _IFT_BoundaryCondition_PrescribedValue "prescribedvalue" ///< [rn] Specifies the prescribed value.
#define _IFT_BoundaryCondition_PrescribedValue_d "d" ///< [rn] Alternative input field for the prescribed value.
#define _IFT_BoundaryCondition_SomeOptionalValue "foobar" ///< [rn,optional,default=100]  Optional foobar parameter.
//@}

which should work with the doxygen documentation as well.
We would allow a much more limited syntax than doxygen, but something a python script would be able to collect from all the files automatically (and transforming it to some suitable LaTeX). For elements, we could link to the specific figures needed.

For pre-processors:
The information above is not quite enough. We need more details, e.g. number of nodes, order, geometry type, etc. All those details should be doable. But
it becomes tricky because some components have rather complex initializeFrom-functions. A parameter might be optional if-and-only-if another parameter is optional. Adding this type of information would be very difficult.
Either a simple grouping or heirarchy of parameters, or we just list them all and specify the necessary combinations in the description, leaving it up to the user. The latter seems like the more reasonable choice.

We could however, also choose a different route here. By linking OOFEM with a pre-processor (as a library), we could have specialized functions that can specify much more complex information for the pre-processor than what is manageable by the text-only doxygen block.
Linking OOFEM as a library also has other benefits. You can use DynamicInputRecord + DynamicDataReader to create complete problems in-code (but this is all a more long-term goal of mine).

2

Re: Modularity on documentation and input record fields

I would add here that when such a input-record description language will be available, we can also think about generating the i/o part of initializeFrom and similar methods automatically. Ideally, the syntax should be simple enough to allow c preprocessor generation when compiling oofem itself, without requiring other tools, but this may be limiting factor.

Just to push forward the discussion here, each record definition should contain:
1) class_variable_name
2) variable_type (int (in), double (rn), array(ia, ra), ...)
3) optional flag and default value
4) description

The input record description language should allow for some simple tests, to allow some basic logic to be included.
- test if optional value has been set
- test for value (scalar values only? operators supported?)

Re: Modularity on documentation and input record fields

Many components check the sizes of the input (e.g. some vector should have the same number of components as some other vector) etc.
We should just most all of that into checkConsistency (which makes sense). This should simplify a lot of intializeFrom-methods.

Tests for which values are set could be handled by a simple optional dependency (one-way dependency should suffice), so I would then add
5) dependency
A (single) dependency could also be handled very easily in pre-processors.

As far as I can tell, there are 2 other types of common logic constructions:
1. Test by value of another parameter (usually on integers, sometimes floats).
2. One of N-optional arguments must be supplied (i.e. semi-optional). We should just do this with checkConsistency instead.


Some of the most complex intializations are for example
HellmichMaterial :: initializeFrom
IsotropicDamageMaterial1 :: initializeFrom
It would probably be easier to rewrite them to work with a simplified logic instead.