Merge branch 'release3.7'

Documentation/Doxygen/building_a_plugin.dox

@@ -1,7 +1,7 @@
 /**
 \page building_a_plugin Building a Plugin
 
-In order to build a plugin you need to have the FEBio SDK (Software Development Kit). This SDK contains the header files and the pre-built libraries that you need to create a plugin. The SDK can be obtained from the febio website www.febio.org and is usually installed in the same location as FEBio usually in a subfolder named sdk). Next, you need a C++ compiler since the plugin has to be written in C++. We also recommend having an IDE (Integrated Development Environment) as this makes writing code much easier (e.g. Visual Studio on Windows, or XCode on Mac). Select one of the following links to learn more about setting up a plugin project for a specific operating system.
+In order to build a plugin you need to have the FEBio SDK (Software Development Kit). This SDK contains the header files and the pre-built libraries that you need to create a plugin. The SDK is installed (optionally) as part of the FEBio Studio installation and is usually installed in the same location as FEBio in a subfolder named sdk). Next, you need a C++ compiler since the plugin has to be written in C++. We also recommend having an IDE (Integrated Development Environment) as this makes writing code much easier (e.g. Visual Studio on Windows, or XCode on Mac). Select one of the following links to learn more about setting up a plugin project for a specific operating system.
 
 \li \subpage create_plugin_vs
 \li \subpage create_plugin_osx

Documentation/Doxygen/callback.dox

@@ -3,7 +3,7 @@
 
 An easy, although somewhat limited, way to extend FEBio's capabilities is by defining callbacks. A callback is a function that is defined by the user and is called by the FEBio framework at specific places in the code. 
 
-FEBio uses this callback mechanism to accomplish several things. A callback is used to update the title of the shell window to display the progress, to query for user interruptions (ctrl+c), and to write the output to the log and plot file.
+FEBio uses this callback mechanism to accomplish several things: A callback is used to update the title of the shell window to display the progress, to query for user interruptions (ctrl+c), and to write the output to the log and plot file.
 
 To register a callback function, call the FEModel::AddCallback function. 
 

Documentation/Doxygen/cb_plugin.dox

@@ -68,7 +68,7 @@ In order to use a callback plugin, it must be registered with the framework. Thi
 REGISTER_FECORE_CLASS(MyCallbackPlugin, "my_callback");
 \endcode
 
-Once the plugin is registered, it can be reference in the FEBio input file. A special Code section can be added where the callbacks can be defined. 
+Once the plugin is registered, it can be referenced in the FEBio input file. A special Code section can be added where the callbacks can be defined. 
 
 \code
 <Code>

Documentation/Doxygen/create_plugin_vs.dox

@@ -23,6 +23,10 @@ Next, we'll need to tell Visual Studio where to find the FEBio header (.h) and l
 Locate the VC++ Directories in the Configuration Properties. In the Include Directories, add the path to the include files (e.g. "C:\Program Files\FEBio2\sdk\include"). To do this, select the "Include Directories" property and click the button on the right of the text edit field. Select "Edit..," from the popup menu. In the dialog box that pops up, the FEBio include folder can be added. Close OK when done. Then,
 add the path to the FEBio library files to the "Library Directories field" (e.g. "C:\Program Files\FEBio3\sdk\lib\"). When done, press the OK button.
 
+It is also necessary to define the WIN32 preprocessor macro. This can be set in the Properties dialog box under the Configuration Properties\C/C++\Preprocessor. Then add WIN32 to the Preprocessor definitions. 
+
+Note that the previous steps need to be done for both the Debug and Release configurations separately. Also make sure to link to the FEBio debug libraries when building the Debug configuration of your plugin, and similarly link to the FEBui release libraries when building the Release configuration. Using the wrong libraries may lead to build or runtime errors. Keep in mind that using the debug libraries may result in poor performance. This is to be expected. The debug libraries should only be used for initial testing and debugging. The release libraries should be used for the actual simulations. 
+
 \image html create_plugin_with_vs_step_4.png
 
 Now you are ready to write your plugin. 

Documentation/Doxygen/factory_classes.dox

@@ -5,7 +5,7 @@ Before a plugin class can be recognized by FEBio it must be registered with the
 
 \section init_plugin Using PluginInitialize
 
-The PluginInitialize is one of the required functions and will be called by FEBio after it loads the plugin file. In this function a plugin can and allocate and initialize any resources it may need. In this function the plugin classes can be registered using the REGISTER_FECORE_CLASS macro. However, before this macro is used it is important to call FECoreKernel::SetInstance with the parameter that is passed to PluginInitialize. 
+The PluginInitialize is one of the required functions and will be called by FEBio after it loads the plugin file. In this function a plugin can allocate and initialize any resources it may need. In this function the plugin classes can be registered using the REGISTER_FECORE_CLASS macro. However, before this macro is used it is important to call FECoreKernel::SetInstance with the parameter that is passed to PluginInitialize. 
 
 \code
 FECORE_EXPORT void PluginInitialize(FECoreKernel& fecore)
@@ -18,7 +18,7 @@ FECORE_EXPORT void PluginInitialize(FECoreKernel& fecore)
 }
 \endcode
 
-The first call the FECoreKernel::SetInstance is important to make sure that the plugin and FEBio are using the same kernel. Without this call, all classes will be registered with a local copy of the kernel and FEBio will not know of any new classes that are registered.
+The first call the FECoreKernel::SetInstance is important to make sure that the plugin and FEBio are using the same kernel. Without this call, all classes will be registered to a local copy of the kernel and FEBio will not know of any new classes that are registered.
 
 The macro REGISTER_FECORE_CLASS takes two parameters. The first parameter is the name of a plugin class. The second parameter is a name that will be used to represent this class in the FEBio input file. 
 

Documentation/Doxygen/febio.dox

@@ -2,7 +2,7 @@
 \page febio Overview of FEBio
 
 FEBio is a finite element solver that is specifically designed for biomechanical applications. It solves the nonlinear finite
-element equations using a quasi-Newton method. It offers  biologically relevant constitutive models and modeling scenarios.
+element equations using a quasi-Newton method. It offers biologically relevant constitutive models and modeling scenarios.
 
 The source code is organized into different modules, each module implemented in a separate library. 
 The following figure shows the relationship between the different modules.

Documentation/Doxygen/febiolib.dox

@@ -2,7 +2,7 @@
 
 \page febiolib Extending the FEBio Library
 
-Although the plugin framework is the recommended way for extending FEBio's feature set, people who so choose can also extend the FEBio library directly. Also, people who want to integrate FEBio in their own code, must work of the FEBio lirary. 
+Although the plugin framework is the recommended way for extending FEBio's feature set, people who so choose can also extend the FEBio library directly. Also, people who want to integrate FEBio in their own code, must work with the FEBio lirary. 
 
 \li \subpage register
 \li \subpage callback

Documentation/Doxygen/index.dox

@@ -1,6 +1,6 @@
 /**
 \mainpage FEBio Developer's Manual
-The FEBio Developer's Manual describes how to extend the default feature set of FEBio. There are several ways in which this can be done. The source code is available for download so users can make their changes directly there. FEBio can also be used as a static library which makes it easy to use in other programs. FEBio also has a plugin mechanism that allows users to add new features without changing the source code or building the entire source code tree.
+The FEBio Developer's Manual describes how to extend the default feature set of FEBio. There are several ways in which this can be done. The source code is available for download (https://github.com/febiosoftware/FEBio). Users can download or clone the github repo and make their changes directly in the source code. FEBio can also be used as a static library, which makes it easy to use FEBio in other codes. FEBio also has a plugin mechanism that allows users to add new features without changing the source code or building the entire source code tree.
 
 \li \subpage febio
 \li \subpage plugins
@@ -9,5 +9,5 @@ The FEBio Developer's Manual describes how to extend the default feature set of
 
 The FEBio software is developed at the Musculoskeletal Research Laboratories at the University of Utah and at the Musculoskeletal Biomechanics Laboratory at Columbia University.
 
-All rights reserved. Copyright (c) 2006 - 2021
+All rights reserved. Copyright (c) 2006 - 2022
 */

Documentation/Doxygen/material.dox

@@ -5,7 +5,7 @@ In this section we will look at the details of setting up a plugin that implemen
 
 The basic procedure for creating a new material for FEBio requires the following steps.
 
-1. Defining a new material class by deriving it from an available base class.
+1. Defining a new material class by deriving it from an suitable base class.
 2. Registering the material with FEBio's framework.
 3. Defining the material parameters.
 4. Implementing the Init() and Validate() functions (optional)
@@ -277,14 +277,14 @@ FEBio will recognize the type identifier as the name of the MyFancyMaterial clas
 Material parameters are identified in a similar way. For each material parameter, the ADD_PARAMETER macro associates a name with the parameter. For example, imagine that for our new class MyFancyMaterial the following parameter is defined,
 
 \code
-ADD_PARAMETER(m_a, "param_a");
+ADD_PARAMETER(m_a, "a");
 \endcode
 
 The user can now enter a value for this parameter in the FEBio input file as follows,
 
 \code
 <material id="1" type="fancy material">
- <param_a>0.123</param_a>
+ <a>0.123</a>
 </material>
 \endcode
 

Documentation/Doxygen/restart.dox

@@ -1,7 +1,7 @@
 /**
 \page restart Restart Capabilities
 
-FEBio has several mechanism for restarting a problem. The "running restart" capability allows the model to recover from a fatal error during runtime and restart
+FEBio has several mechanism for restarting a problem. The "running restart" capability allows the model to recover from an otherwise fatal error during runtime and restart
 from the last converged state. The "cold restart" allows the user to restart an analysis using a restart file. Again, the analysis will restart from the last converged state (for which a dump file was created). 
 The "reset" feature allows a user to reset all data and restart the analysis from scratch. The following sections describe these features in more detail.
 

Documentation/Doxygen/serialize.dox

@@ -1,16 +1,15 @@
 /**
 \page serialize Data Serialization
 
-Data serialization refers to the process of reading and writing class data to or from an external file. This feature is used for the (cold) restart capability, that
+Data serialization refers to the process of reading and writing class data to or from an external file. This feature is used for the restart capabilities, that
 allows an analysis to restart from a previous state.
 
 Most aspects of serialization is taken care of by the framework, however in some cases a class needs to implement additional support by implementing the \c Serialize member. 
-This function takes a single parameter, namely the so-called dump file. 
+This function takes a single parameter, namely the dump stream. 
 
 \code
-void MyClass::Serialize(DumpFile& ar)
+void MyClass::Serialize(DumpStream& ar)
 {
- FEModel& fem = *ar.GetFEModel();
  if (ar.IsSaving())
  {
  // write data using the << operator
@@ -22,7 +21,52 @@ void MyClass::Serialize(DumpFile& ar)
 }
 \endcode
 
-The FEModel that the class belongs to can be recovered from <c>DumpFile::GetFEModel()</c>. Data is written to the dump file using the << operators (just like when
-using std::cout). Data is read from the dump file using the >> operators (just like using std::cin). Note that it is important that data is read in the same order
-as it was written. 
+Data is written to the dump stream using the << operators (just like when using std::cout). Data is read from the dump file using the >> operators (just like using std::cin). Note that it is important that data is read in the same order as it was written. 
+
+Alternatively, you can use the ampersand operator (&), which will write on saving and read on loading. 
+
+For instance, consider a class, MyClass, that defines two parameters, m_a and m_b. You can serialize using either the explicit read and write operators. 
+
+\code
+void MyClass::Serialize(DumpStream& ar)
+{
+ if (ar.IsSaving())
+ {
+ ar << m_a << m_b;
+ }
+ else
+ {
+ ar >> m_a >> m_b;
+ }
+}
+\endcode
+
+Alternatively, the following code is equivalent. 
+
+\code
+void MyClass::Serialize(DumpStream& ar)
+{
+ ar & m_a & m_b;
+}
+\endcode
+
+\section ser_sec1 Shallow vs Deep Serialization
+
+The serialization is used during running restarts and cold restarts. A running restart happens when a time step fails and the model's state needs to be restored to the last converged time step so that a new time step size can be tried. A cold restart happens when a model is restarted from a dump file (or restart input file). 
+
+During a running restart, not all of the model data needs to be serialized. (For instance, initial nodal coordinates, constant material parameter, and other values that do not change during the solution process.) In this case, only a "shallow" copy of the model needs to be stored to the dumpstream. This is in contrast to the cold restart, when a "deep" copy needs to be read, since all model parameters need to be restored from the dumpstream. 
+
+You can check whether a shallow or deep copy needs to be serialized using the \c DumpStream::IsShallow function. For instance, the following code illustrates how to serialize data for cold restarts. 
+
+\code
+void MyClass::Serialize(DumpStream& ar)
+{
+ if (ar.IsShallow() == false)
+ {
+ ar & m_a & m_b;
+ }
+}
+\endcode
+
+
 */

Documentation/Doxygen/task.dox

@@ -25,9 +25,9 @@ class MyTask : public FECoreTask
 public:
  MyTask(FEModel* pfem);
 
- bool Init(const char* szfile);
+ bool Init(const char* szfile) override;
 
- bool Run();
+ bool Run() override;
 }
 \endcode
 
@@ -46,9 +46,7 @@ This function should at least call the FEModel::Init function to initialize the
 after these changes. Once FEModel::Init is called, a task should not add to or remove any model components to the FEModel.
 
 \subsection task_sec13 Implement the Run function
-After FEBio is done initializing the model data, it will call the selected task's Run function and passes the main execution loop to the task. The parameter passed to the Run
-function is a (optional) filename that was passed on the command line after the -task=[task_name] command. Note that this will not be the model input file (specified with -i) and
-this parameter can be NULL. 
+After FEBio is done initializing the model data, it will call the selected task's Run function and passes the main execution loop to the task.
 
 Inside the Run() function, the task can execute the code that implements the task. After completing, the Run() function must return a boolean indicating whether the task was executed
 successfully (true) or not (false). 

Documentation/Doxygen/using_plugins.dox

@@ -19,7 +19,7 @@ If you wish to load many plugins, and these plugins are all located in the same
 <import>$(PluginFolder)\plugin.dll</import>
 \endcode
 
-When FEBio starts it will read the configuration file and try to load all plugins listed therein. A message will be printed on the screen at the start of an FEBio analysis indicating if FEBio was successful in loading the plugin.
+When FEBio starts, it will read the configuration file and try to load all plugins listed therein. A message will be printed on the screen at the start of an FEBio analysis indicating if FEBio was successful in loading the plugin.
 
 Alternatively, you can add the path to a plugin to the FEBio command line with the <c>-import</c> command line option.