Commit c355ef4c authored by Turnhout, M.C. van's avatar Turnhout, M.C. van
Browse files

fix merge conflicts

parents 73bc0dff e3162f6e
Pipeline #3449 failed with stages
......@@ -127,3 +127,7 @@ octave-workspace
*.uvw
*.deF
*.sig
documentation/*.f
documentation/paramspace/*.f
!documentation/pics/*.pdf
!documentation/paramspace/*.7z
......@@ -37,14 +37,14 @@ from stexmf: http://mategit.wfw.wtb.tue.nl/STEM/stexmf
copyright
=========
Copyright (C) 2017 Inge A.E.W. van Loosdregt, Department of Biomedical
original Matlab code: Copyright (C) 2018 Inge A.E.W. van Loosdregt, Department of Biomedical
Engineering, Eindhoven University of Technology.
Copyright (C) 2017 Sandra Loerakker, Department of Biomedical
Fortran & FEM code: Copyright (C) 2018 Sandra Loerakker, Department of Biomedical
Engineering, Eindhoven University of Technology.
Copyright (C) 2018 Soft Tissue Engineering and Mechanobiology (STEM)
group, Department of Biomedical Engineering, Eindhoven University of
TFlab: Copyright (C) 2018 Soft Tissue Engineering and Mechanobiology (STEM)
group, Department of Biomedical Engineering, Eindhoven University of
Technology: http://www.stem-research.nl https://www.tue.nl/stem
This program is free software; you can redistribute it and/or modify
......
% !TeX root = TFlab.tex
\begin{savequote}
In the computer model, all the microfilaments were given certain quantitative properties with names that mean something to physicists: a `viscous damping coefficient' and an `elastic spring constant'. Never mind exactly what these mean: they are the kind of things physicists like to measure in a spring. \qauthor{Richard Dawkins \cite{Dawkins2009}}
\end{savequote}
\chapter{The Finite Element Model}\label{thefem}
The finite element model is implemented in Simulia Abaqus (Dassault Syst{\`e}mes Simulia corp., Providence, RI, USA) and uses some Fortran user subroutines to get specific things done (table \ref{feminputfiles}). The main Fortran file to feed to Abaqus is \texttt{main.f}. So a call to Abaqus for a simulation might look like:
\begin{lstlisting}[numbers=none]
mark@telab11:~$ abaqus job=<expname>_film1_frame1 input=<expname>_film1.inp user=main.f cpus=4
\end{lstlisting}
From Matlab, using \tflab, you could call:
\begin{lstlisting}[numbers=none]
>> [stat, res] = TF_runFEM(param, film, frame)
\end{lstlisting}
~\\
The input file \texttt{<expname>\_film1.inp} is written by \TF{writeFEM} or \TF{buildFEM} (section \ref{fembuild}). The appropriate function is called from \TF{runFEM} (and thus from \TF{estsigmax}) when the input file doesn't exist yet.\\
\noindent Note that a single Abaqus input file suffices for all frames of a given film. Input files (for all frames) will be named \texttt{<}\param{expname}\texttt{>\_film$i$.inp}. However, $\sigma_x$ is unique for each frame, so the Abaqus \textsl{job} name \textsl{does} include the frame number $j$: \texttt{<}\param{expname}\texttt{>\_film$i$\_frame$j$}.
The unique $\sigma_x$ for each frame is stored in a file \paraminc{}, which is overwritten for each frame. So \tflab{} copies \paraminc{} to \texttt{<}\param{expname}\texttt{>\_film$i$\_frame$j$.inc} after a simulation for future reference. Also note, therefore, that the material model subroutine \texttt{umat.f} will attempt to read from that file \paraminc{} (section \ref{paraminc}).
\section{Mesh and boundary conditions}
The finite element model consist of two layers of elements in $\vec{x}\vec{y}$-plane, one layer for the substrate, one for the cells (figure \ref{FEmesh}).
\begin{figure}
\includegraphics[width=\linewidth]{pics/FEmesh.png}
\caption{Default mesh of $10\times20\times2$ elements with `encastre' boundary condition at the vertical plane (substrate only) at $y = 0$. \label{FEmesh}}
\end{figure}
Both substrate and cells are meshed with quadratic 20-node continuum brick elements (\href{http://furnace.wfw.wtb.tue.nl:2080/texis/search/hilight2.html/+/usb/pt06ch28s01ael03.html?CDB=v6.14#d0e304283}{C3D20}).
The vertical $\vec{x}\vec{z}$-plane of the substrate (only) at $y = 0$ has all degrees of freedom suppressed (\href{http://furnace.wfw.wtb.tue.nl:2080/texis/search/hilight2.html/+/usb/pt07ch34s03aus118.html?CDB=v6.14#usb-prc-pboundary-xsymm}{`encastre'}, figure \ref{FEmesh}).
The model includes node sets for the `left edge bottom nodes' (\texttt{lebn}) and the `right edge bottom nodes' (\texttt{rebn}), which are needed for the projected film length analysis (\TF{getFEMR}).
The model writes relevant information for \TF{estsigmax} (or indeed: the user) to human and Matlab readable text files (\texttt{.xyz} \& \texttt{.uvw}, table \ref{femoutputfiles}).
\section{Material models}
Both substrate and cells are modelled with an isotropic compressible Neo-Hookean material model \cite{Oomens2018}:
\begin{equation}
\ten{\sigma}_C = \kappa \frac{\ln J}{J}\ten{I}+\frac{G}{J}\left(\ten{B}-J^\frac{2}{3}\ten{I}\right)\label{neohooke}
\end{equation}
With $\ten{\sigma}_C$ the Cauchy stress, $\kappa$ the compression modulus, $J$ the determinant of the deformation gradient tensor $\ten{F}$, $\ten{I}$ the identity tensor, $G$ the shear modulus and $\ten{B} = \ten{F}\cdot\ten{F}^\text{T}$ the Finger strain tensor (or: left Cauchy-Green strain tensor). The shear modulus $G$ and compression modulus $\kappa$ can be derived from the Youngs modulus $E$ and Poisson ratio $\nu$:
\begin{align}
G & = \frac{E}{2(1-\nu)}\\
\kappa & = \frac{2G(1+\nu)}{3(1-2\nu)}
\end{align}
The material models for both substrate and cells are programmed in the Fortran user routine \texttt{umat.f}, and both use $E$ and $\nu$ to define the material properties. For the substrate, the user can set the Youngs modulus with \param{Efilm} and the Poisson ratio with \param{vfilm}; for the cells the user can set the Youngs modulus with \param{Ecells} and the Poisson ratio with \param{vcells}
\subsection{Cell traction stress}
An (active) cell traction component is added to the Cauchy stress in equation \ref{neohooke} for the cells. The total stress for the cells $\ten{\sigma}_t$ is therefore the sum of the Cauchy stress in equation \ref{neohooke} and the active cell traction stress $\ten{\sigma}_a$:
\begin{equation}
\ten{\sigma}_t = \ten{\sigma}_C + \ten{\sigma}_a
\end{equation}
The active component can only work in the direction of the fibres and is calculated with:
\begin{equation}
\ten{\sigma}_a = \sum_{n = 1}^{N} \varphi_n\sigma_x \left(\vec{e}_n\otimes\vec{e}_n\right) \label{activestress}
\end{equation}
With $ \varphi_n$ the stress fibre volume fraction for the $n$\ap{th} direction (and $\sum \varphi_n \doteq 1$), $\sigma_x$ the active cell stress to be estimated, and $\vec{e}_n$ the stress fibre direction of the $n$\ap{th} direction in the deformed mesh.
\tflab{} uses $N = 30$ orientations, equally spaced between $0 < \phi < \piup$ (section \ref{conv:actin}).
\subsection{\paraminc{}}\label{paraminc}
The material parameters that are needed by the Fortran routine \texttt{umat.f} and that are not hard-coded, are read from a (Fortran) file \paraminc{}:\\
\lstinputlisting[language=fortran]{param.inc}
\texttt{Ep} is the substrates Youngs modulus in MPa, \texttt{sigmax} is the active cell stress ($\sigma_x$, equation \ref{activestress}) in MPa, and \texttt{phi\_sf($n$)} are the 30 fibre orientation volume fractions ($\varphi_n$, equation \ref{activestress}).
This file is written by \TF{writeFEMinc} which is automatically called before an analysis is attempted from \tflab.
\section{Matlab or Python}\label{fembuild}
There are two ways to obtain an Abaqus input file in \tflab: Matlab/hard-coded and Python/`free-form'.
\subsection{Matlab (hard-coded)}
For films that do not deviate too much from the dimensions that Inge used (about 4\,mm long, 1.75\,mm wide), you can have \tflab{} write the Abaqus input file directly without calling Abaqus with a Python script. The number of elements ($20\times10\times2$) is hard-coded for this method.
The benefit of this method is that is \textsl{fast}. We do not need to write python scripts and call Abaqus to build the model, and we do not have to parse the input file for the mesh and the node sets.
This method requires \texttt{param.buildFEM = 'matlab'} (in any permutation of capitalisation imaginable, appendix \ref{matcaps}) and uses \TF{writeFEM} to write the Abaqus input file.
\subsection{Python (free)}
For films that \textsl{do} deviate from the dimensions that Inge used, the hard-coded Matlab method may result in elements with suboptimal dimensions (e.g.\ aspect ratios). In that case, you can have \tflab{} write an Abaqus Python script that will create the Abaqus input file. With this method, the number of the elements is set by the user (\param{nelx}, \param{nely}).
The benefit of this method is the larger freedom of geometries and meshes. You can also run the script in the Abaqus cae GUI and have the entire model properly at your disposal (as opposed to importing an input file).
This method requires \texttt{param.buildFEM $\neq$ 'matlab'} and uses \TF{buildFEM} to write the python file that is fed to Abaqus so that Abaqus can write input file (so that \TF{runFEM} can feed the input file to Abaqus).\\
\noindent Note that this method depends on \texttt{aba\_readmesh.m} from \href{http://mategit.wfw.wtb.tue.nl/STEM/abalab}{abalab} for parsing of the input file for the mesh and the node sets. \warning
\section{Parameters}
There are a number of parameters and settings in \TF{labconfig} that affect the finite element simulations and that can be configured by the user (chapter \ref{TFconf}).
Note that these settings are never explicitly checked or validated in \tflab{}: e.g.\ \TF{prepexp} will not ask to confirm or change these values. If the end-user wishes to use different settings than those provided in the current default configuration (chapter \ref{TFconf}), said user should change these pro-actively.\\
\noindent \param{FEMbuild}
Set this parameter to \texttt{'matlab'} (in any permutation of capitalisation imaginable) for a hard-coded mesh and input file (default), and set it to something else for a `free' mesh and input file (section \ref{fembuild}).\\
\noindent \param{nelx}, \param{nely}
Set the number of elements in $\vec{x}$-direction (width) and $\vec{y}$-direction (length) when \texttt{param.buildFEM $\neq$ 'matlab'}.\\
\noindent \param{mininc}
Sets the minimum time increment for the simulations. When your simulation does not converge, Abaqus will attempt to use a smaller time increment. This parameter tells Abaqus when to give up with reducing the size of the time increments.\\ All simulations take 1\,s in total, the default for \param{mininc} is \texttt{1e-5}\,s.\\
\noindent \param{maxinc}
Sets the maximum \textsl{number} of time increments for the simulations.\\ Default: \param{mininc}\texttt{ = 1e3}.\\
\noindent \param{nCPU}
Tells Abaqus how many CPU cores to use for the calculations.\\ Default: \param{nCPU}\texttt{ = 4}.\\
\noindent \param{submit}
When \texttt{param.buildFEM $\neq$ 'matlab'}, you can have \tflab{} write an extra line to the python file that immediately submits the job when the input file has been written: \param{submit}\texttt{ = 1}.\\
Default: \param{submit}$ = 0$ (do not automatically submit job).\\
\section{Files}\label{femfiles}
A plethora of files is involved in our Abaqus finite element simulations, not all of 'em equally interesting.
\begin{table}[h!]
\center
\caption{Necessary files for a finite element simulation with Abaqus. \label{feminputfiles}}
\begin{tabularx}{\linewidth}{l X r}
\hline\noalign{\smallskip}
file & description & source \\ \noalign{\smallskip}\hline\noalign{\smallskip}
\texttt{<expname>\_film$i$.inp} & Abaqus input file for film $i$, & \TF{writeFEM} \\
& contains the model & \TF{buildFEM}\\
\texttt{main.f} & main Fortran user routine, calls or reads the rest & \tflab \\
\texttt{umat.f} & user material subroutine, calculates $\sigma$ for Abaqus & \tflab \\
\texttt{getstress\_neohooke.f} & called by \texttt{umat.f}, calculates $\sigma_C$ (equation \ref{neohooke}) & \tflab \\
\texttt{getstress\_stressfibers.f} & called by \texttt{umat.f}, calculates $\sigma_a$ (equation \ref{activestress}) & \tflab \\
\texttt{urdfil.f} & writes desired results to text files during simulations & \tflab \\
\texttt{utils.f} & some utilities used and called throughout & \tflab \\
\paraminc{} & file with material properties for \texttt{umat.f} (section \ref{paraminc}) & \TF{writeFEMinc}\\\noalign{\smallskip}\hline
\end{tabularx}
\end{table}
\subsection{Necessary FEM input files}
In order to be able to run our analysis, we need an Abaqus input file, our Fortran scripts, and a (Fortran) file with material properties (table \ref{feminputfiles}). The Fortran files are static (same scripts, always) and are copied from the \tflab-installation directory (c.q.\ the sub directory \texttt{fortran}) when necessary. The Abaqus input file and the material properties file are film and frame dependent, and are produced by \tflab.
\subsection{FEM results files}
For our analysis, we have Abaqus write results to human and Matlab readable text files (table \ref{femoutputfiles}). These files are the
main outcome of analysis and should be kept (not deleted) at all costs.
\begin{table}[h]
\center
\caption{Necessary files produced with a finite element simulation with Abaqus. \label{femoutputfiles}}
\begin{tabularx}{\linewidth}{l X r}
\hline\noalign{\smallskip}
file & description & source \\ \noalign{\smallskip}\hline\noalign{\smallskip}
\texttt{<expname>\_film$i$\_frame$j$.xyz} & text file with nodal coordinates of the undeformed mesh for frame $j$ of film $i$ & \texttt{urdfil.f} \\
\texttt{<expname>\_film$i$\_frame$j$.uvw} & text file with nodal displacements of the deformed mesh at each increment for frame $j$ of film $i$ & \texttt{urdfil.f} \\
\texttt{<expname>\_film$i$\_frame$j$.est} & text file with simulated values of $\sigma_x$ and the resulting projected film length $l$ for frame $j$ of film $i$ (when estimating $\sigma_x$, section \ref{estfiles}) & \TF{estsigmax} \\\noalign{\smallskip}\hline
\end{tabularx}
\end{table}
\subsection{Useful FEM files}
An Abaqus simulation produces a binary `output database' with all the simulations results (other than just the text files from table \ref{femoutputfiles}), and a number of files with information that can be useful for debugging when your simulation fails (table \ref{femusefiles}). If all goes well, these files may be redundant.
\begin{table}[h]
\center
\caption{Useful files produced with a finite element simulation with Abaqus. \label{femusefiles}}
\begin{tabularx}{\linewidth}{l X r}
\hline\noalign{\smallskip}
file & description & source \\ \noalign{\smallskip}\hline\noalign{\smallskip}
\texttt{<expname>\_film$i$\_frame$j$.odb} & The Abaqus Output DataBase, contains the results of the simulation in binary (Abaqus) format for frame $j$ of film $i$. Can be opened and read with Abaqus cae or Abaqus viewer. & Abaqus \\
\texttt{<expname>\_film$i$\_frame$j$.dat} & text file that contains the results of Abaqus' parsing of the input file for frame $j$ of film $i$. When something is wrong with your input file, the \texttt{dat}-file tells you what it is. & Abaqus \\
\texttt{<expname>\_film$i$\_frame$j$.msg} & text file that contains Abaqus messages during the simulation for frame $j$ of film $i$. When your simulation fails, the \texttt{msg}-file may tell you what the reason is. & Abaqus \\
\texttt{<expname>\_film$i$\_frame$j$.sta} & text file that contains the progress of the simulation for frame $j$ of film $i$. You can monitor this file to see how well your simulations runs, converges.\\\noalign{\smallskip}\hline
\end{tabularx}
\end{table}
\subsection{Redundant FEM files}
The files in table \ref{femextrafiles} \textsl{are} redundant as far as the user is concerned. Most of these files are temporarily and will be deleted by Abaqus after a `successful' simulation (successful not meaning: converged to the end). These files may be left on your PC when you kill, break off, an Abaqus job. They can be deleted (but not for a running simulation, of course).
\begin{table}[h]
\center
\caption{Redundant files produced with a finite element simulation with Abaqus. These files are produced by Abaqus and most are also deleted by Abaqus after a successful simulation.\label{femextrafiles}}
\begin{tabularx}{\linewidth}{l X r}
\hline\noalign{\smallskip}
file & description & deleted? \\ \noalign{\smallskip}\hline\noalign{\smallskip}
\texttt{<expname>\_film$i$\_frame$j$.com} & text file that contains some Abaqus modelling parameters. & no\\
\texttt{<expname>\_film$i$\_frame$j$.fil} & binary file that contains the results that were written by \texttt{urdfil.f} to text files. & no\\
\texttt{<expname>\_film$i$\_frame$j$.1.SMABulk} & binary file& yes\\
\texttt{<expname>\_film$i$\_frame$j$.1.SMAFocus} & binary file & yes\\
\texttt{<expname>\_film$i$\_frame$j$.023} & binary file & yes\\
\texttt{<expname>\_film$i$\_frame$j$.cid} & text file, contains the name of your computer and some numbers & yes\\
\texttt{<expname>\_film$i$\_frame$j$.lck} & 'lock'-file that tells Abaqus that that job is already running. & yes\\
\texttt{<expname>\_film$i$\_frame$j$.mdl} & binary file& yes\\
\texttt{<expname>\_film$i$\_frame$j$.prt} & a text file with plenty numbers & no\\
\texttt{<expname>\_film$i$\_frame$j$.sst} & binary file & yes\\
\texttt{<expname>\_film$i$\_frame$j$.sim} & xml (text) file that points to the two \texttt{.SMA...}-files & no\\
\texttt{<expname>\_film$i$\_frame$j$.log} & text file with the output that Abaqus writes to stdout and stderr (i.e.\ the command line). & no\\\noalign{\smallskip}\hline
\end{tabularx}
\end{table}
\subsection{Extra files for \texttt{param.buildFEM $\neq$ 'matlab'}}
If you use the `free' form python building for your input files, you will also find a file \texttt{<expname>\-\_film$i$.py}. This is the python file that Abaqus used to build the input file. This file can be reproduced from the param-structure, but I, for one, would keep it (and I'd probably keep it in favour of the actual input files, since those will be larger).
If you use the `free' form python building for your input files, you may also find files starting with \texttt{abaqus.rpy} (possibly followed by another period and a number) in your working directory. These are redundant.
% !TeX root = TFlab.tex
\begin{savequote}
Two other journals allowed an engineer posing as Maggie Simpson and Edna Krabappel to publish a paper, ``Fuzzy, Homogeneous Configurations.'' \qauthor{Christie Aschwanden \cite{Aschwanden2015}}
\end{savequote}
\chapter{\TF{labconfig}}\label{TFconf}
\tflab{} comes with a central configuration script \TF{labconfig}. \\ The objective of this script is first:
\begin{enumerate}
\item to ensure that all \tflab{} scripts use the same defaults values for missing parameters; and
\item to provide a central `database' to hold these default values (so that the developers know where to find 'em).
\end{enumerate}
This has been taken care of by your favourite \tflab{} developers with \TF{labconfig}: the end-user need not worry 'bout a thing \cite{Wonder1973}.\\
\noindent Second, \TF{labconfig} allows the user to
\begin{enumerate}[resume]
\item to change these default values globally (for \tflab{}), and locally (for the working directory) (sections \ref{configfiles} \& \ref{writeaddwipe}); and
\item to write a full report of the current (local, working directory) defaults to a configuration script (section \ref{repwrite}).
\end{enumerate}
This functionality is explained in more detail in this appendix.\\
\noindent Note that the commands showcased in this appendix \textsl{will} mess with existing configurations. That is also the reason that we do not provide a \TF{example} for \TF{labconfig}: (accidentally) running such an example would mess with existing configurations.
So if you have a(n) existing configuration script(s) in place, use these commands with care, or: not at all.\warning
\section{User configuration scripts}\label{configfiles}
Because (all) defaults for all scripts are collected in the single script \TF{labconfig}, it is easy for the user to change e.g.\ the default number of films to \texttt{nfilm} = \texttt{6}, or to change the default \texttt{FEMbuild} from \texttt{'matlab'} to \texttt{'python'}
However, when you download a new (or old) version of \tflab{}, customised \TF{labconfig} files are prone to be overwritten. Also, the end-user may wish to change the defaults \textsl{only} for work in a particular directory, e.g.\ the \textsl{particular} directory where the experiments with 6 films are located. \\
\begin{codefloat}[t!]
\caption{Parsing user configurations in \TF{labconfig}. First we get our own \tflab-defaults in line 19, next we check for global user-setting in the \tflab{} installation directory (lines 20--23), and finally we check for local user-setting in the current working directory (lines 24--27). \label{examlabconfig}}
\begin{lstlisting}[language=tflab, firstnumber=18]
% get the values from the bottom of the file
labdef = getlabdef;
if exist(fullfile(TF_labpath, 'TFlab_globalConfig.m'), 'file')
% load and overwrite with global user settings
labdef = TFlab_globalConfig(labdef);
end
if exist(fullfile(pwd, 'TFlab_localConfig.m'), 'file')
% load and overwrite with global user settings
labdef = TFlab_localConfig(labdef);
end
\end{lstlisting}
\end{codefloat}
\begin{codefloat}[t!]
\caption{Example of a global \texttt{\tflab{}\_globalConfig} user configuration script. With this file in the \tflab{} installation directory, \tflab{} will by default expect 6 films per experiment (line 12), and will by default use python for building of the finite element models (line 13). The `real work' seems to be done between lines 12--14, but lines 1--10 and 15--19 are not bloat, branding, or marketing: they are for seamless integration in \tflab{}.\label{configexam}}
\begin{lstlisting}[language=tflab, title=\texttt{TFlab\_globalConfig.m}]
function labdef = TFlab_globalConfig(iDef)
% labdef = TFlab_globalConfig(iDef)
%
% global TFlab configuration function
%
% See also TF_labconfig
% parse input
if nargin > 0, labdef = iDef; else labdef = []; end
%%%%%%%%%%%%%%%%%%%%%%% do not edit above this line %%%%%%%%%%%%%%%%%%%%%%%
labdef.nfilm = 6;
labdef.FEMbuild = 'python';
%%%%%%%%%%%%%%%%%%%%%%% do not edit below this line %%%%%%%%%%%%%%%%%%%%%%%
% written by TF_labconfig: http://mategit.wfw.wtb.tue.nl/STEM/TFlab
% @ 13-Oct-2018 11:53:14
end
\end{lstlisting}
\end{codefloat}
\noindent \tflab{} comes with the option to overwrite \tflab{}s own default settings with global or local user-configuration scripts: \TF{labconfig} first loads our own \tflab{} default settings, then checks for global user-settings in \texttt{\tflab{}\_globalConfig.m} in \tflab{}s installation directory, and for good measure finally checks the working directory for local user-settings in \texttt{\tflab{}\_localConfig.m} (listing \ref{examlabconfig}).
Since the defaults are processed in this order, user-settings in \texttt{\tflab{}\_globalConfig.m} take precedence over \tflab{}s own defaults, and user-settings in \texttt{\tflab{}\_localConfig.m} take precedence over, well, everything (see also the \texttt{\tflab{}\_configReport.m} in section \ref{repwrite}).
An example of a global user configuration script is shown in listing \eqref{configexam}. Local user configuration scripts are\dots{} similar.
\section{Write, add, and delete settings in \texttt{\tflab{}\_*Config}}\label{writeaddwipe}
The user configuration scripts are proper Matlab functions that can be edited manually (listing \ref{configexam}). However, since \tflab{} expects certain things from these functions (e.g.\ that they \textsl{are} proper Matlab functions, to start with; but e.g.\ also the formatting of the last three lines) we recommend against that.
We certainly recommend against writing your own user-configuration scripts from scratch.\\
\noindent So, to ensure that the configuration scripts perform as \tflab{} expects 'em to perform, you can outsource the editing of these configuration scripts to the \TF{labconfig}-function.
\subsection{Tabula rasa: \texttt{'purge'}}
But first of all: you may wish to start with a clean slate.
The argument \texttt{'purge'} switches \TF{labconfig} to file-deletion-mode, and comes in three flavours:
\begin{lstlisting}[language=tflab]
>> TF_labconfig('purge', 'local'); % remove TFlab_localConfig.m
>> TF_labconfig('purge', 'global'); % remove TFlab_globalConfig.m
>> TF_labconfig('purge', 'all'); % do 1 and 2
\end{lstlisting}
Line 1 will remove the file \texttt{\tflab{}\_localConfig.m} from the directory where \TF{labconfig} is called, line 2 will remove the file \texttt{\tflab{}\_globalConfig.m} from the directory where \tflab{} is installed, and line 3 will do both.\\
\noindent Note. There will be no pop-up asking if you are sure. The file will not be moved to a `recycle bin', it will be \textsl{erased from the system}. \warning For all eternity ever. Using \texttt{'purge'} can lead to some quite definite and irrevocable consequences.
\subsection{Editing: \texttt{'add'} \& \texttt{'delete'}}
The arguments \texttt{'add'} and \texttt{'delete'} allow you to do just that: add settings to, or delete settings from, the global or local configuration script.
If you start with an empty file, listing \ref{configexam} is the result of line 1:
\begin{lstlisting}[language=tflab]
>> TF_labconfig('nfilm', 6, 'FEMbuild', 'python', 'add', 'global')
>> TF_labconfig('tfilm', 'Efilm', 'delete', 'local');
\end{lstlisting}
Settings that you wish to add, should come in \texttt{'name', value}-pairs. And then:
\begin{itemize}
\item If the configuration-script-of-interest does not exist, it will be created.
\item If the \texttt{'name'} for the \texttt{value} is not yet present in the configuration-script-of-interest, a new line will added: \texttt{labdef.name = value;}
\item If the \texttt{'name'} for the \texttt{value} \textsl{is} present in the configuration-script-of-interest, the old line will be replaced by \texttt{labdef.name = value;}
\item You can add multiple \texttt{'name', value}-pairs at once, e.g.\ \texttt{'nfilm', 6} and \texttt{'FEMbuild', 'python'} in line 1 in the example.
\item if you ask \TF{labconfig} to \texttt{'add'} without supplying \texttt{'name', value}-pairs, it will write the complete current configuration to the configuration-script-of-interest. So
\begin{lstlisting}[language=tflab]
>> TF_labconfig('add', 'global');
\end{lstlisting}
will write the current local configuration to the global configuration script.
\end{itemize}
\noindent Settings that you wish to delete, only require their \texttt{'name'} as input. And then:
\begin{itemize}
\item If \texttt{labdef.name = } is present in the configuration-script-of-interest, that line will be removed from the script.
\item You can delete multiple \texttt{'name'}s at once, e.g.\ \texttt{'tfilm'} and \texttt{'Efilm'} in line 2 in the example.
\item \tflab{} handles deletion of non-existent settings in the configuration-script-of-interest with elegance and grace.
\end{itemize}
\subsection{Writing: \texttt{'write'}}
The \texttt{'write'}-argument is similar to the \texttt{'add'}-argument in the sense that is writes the requested \texttt{'name', value}-pairs to your configuration-script-of-interest (global or local). A marked difference is that \texttt{'write'} will write your \texttt{'name', value}-pairs to a new configuration script, always.
So
\begin{lstlisting}[language=tflab]
>> TF_labconfig('nfilm', 6, 'FEMbuild', 'python', 'write', 'global');
\end{lstlisting}
is equivalent to:
\begin{lstlisting}[language=tflab]
>> TF_labconfig('purge', 'global');
>> TF_labconfig('nfilm', 6, 'FEMbuild', 'python', 'add', 'global');
\end{lstlisting}
And if you have a configuration script with five defaults, you can \texttt{'add'} two \texttt{'name', value}-pairs and end up with seven defaults.
But if you \texttt{'write'} two \texttt{'name', value}-pairs, the script will contain those two pairs and those two pairs only. No matter what the previous contents of that script may, or may not, have been.\warning\\
\noindent Settings that you wish to write, should come in \texttt{'name', value}-pairs, as with \texttt{'add'}. And then:
\begin{itemize}
\item If the configuration-script-of-interest exists, it will be discarded and overwritten and gone.
\item You can add multiple \texttt{'name', value}-pairs at once, e.g.\ \texttt{'nfilm', 6} and \texttt{'FEMbuild', 'python'} in line 1 in the example (as with \texttt{'add'}).
\item if you ask \TF{labconfig} to \texttt{'write'} without supplying \texttt{'name', value}-pairs, it will write the complete current configuration to the configuration-script-of-interest (as with \texttt{'add'}). So
\begin{lstlisting}[language=tflab]
>> TF_labconfig('write', 'global');
\end{lstlisting}
will write the current local configuration to the global configuration script\footnote{So in the case of missing \texttt{'name', value}-pairs, \texttt{'add'} and \texttt{'write'} have the same behaviour and result.}.
\end{itemize}
\section{WWW: \texttt{'report'}}\label{repwrite}
At any given moment, you can query the contents of the configuration scripts by just calling
\begin{lstlisting}[language=tflab]
>> TFlab_globalConfig
ans =
nfilm: 6
FEMbuild: 'python'
>> TFlab_localConfig
ans =
nelx: 15
Efilm: 1.3540
\end{lstlisting}
on the Matlab command line. Line 1 works from any directory (if the script exists and \tflab{} is added to the Matlab path), line 8 can (should) only be issued in the directory of the script.
However, the end-user does not really have access to the defaults that have been hard-coded by the developers (other than by investigation of the \TF{labconfig}-script itself).
And for the sake of transparency and reproducibility, for future reference, for logging of your activity, for the `data retention / protection policy', and to end discussions with your supervisor in a glorious victory, these ad-hoc calls on the Matlab command line will of course not do.\\
\noindent The input argument \texttt{'report'} will convince \TF{labconfig} to write an overview of the What, Where and When of the current (local) \tflab{} defaults in the current working directory. \\ So if you were to issue the commands:
\begin{lstlisting}[language=tflab]
>> TF_labconfig('purge', 'all');
>> TF_labconfig('FEMbuild', 'python', 'test', 0, 'add', 'global');
>> TF_labconfig('nfilm', 6, 'test', 1, 'succes', '?', 'add', 'local');
>> TF_labconfig('report');
\end{lstlisting}
you would find a file called \texttt{TFlab\_configReport.m} in the directory where you issued said commands that looks similar to:\\
\begin{lstlisting}[language=tflab, title=\texttt{TFlab\_configReport.m}]
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% TFlab configuration report by TF_labconfig (TFlab)
% generated on: 13-Oct-2018 12:30:04
% for working directory:
% /home/mark/tue/
% and TFlab installation directory:
% /home/mark/git/TFlab/
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% TFlab default parameters:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
labdef.expname = 'default';
labdef.nfilm = 8;
labdef.nframe = 1;
labdef.refframe = 0;
labdef.fibdef = {'iso'};
labdef.Efilm = 1.520000;
labdef.tfilm = 0.006780;
labdef.tcells = 0.002300;
labdef.FEMbuild = 'matlab';
labdef.nelx = 10;
labdef.nely = 20;
labdef.nelz = 1;
labdef.mininc = 0.000010;
labdef.maxinc = 1000;
labdef.nCPU = 4;
labdef.submit = 0;
labdef.curlcheck = 1;
labdef.inisigs = [0.000750, 0.001500];
labdef.cutback = 0.300000;
labdef.lesttol = 0.010000;
labdef.sigesttol = 0.000001;
labdef.simfailtol = 5;
labdef.fancyest = 0.500000;
labdef.instpath = '/home/mark/git/TFlab/';
labdef.intvars = {'refframe', 'nfilm', 'nframe', 'stack', 'curlcheck', 'simfailtol', 'maxinc', 'nelx', 'nely', 'nelz', 'nCPU', 'submit'};
labdef.TFlabUrl = 'http://mategit.wfw.wtb.tue.nl/STEM/TFlab';
labdef.TFlabBranch = 'testing';
labdef.TFlabVersion = '0.1+';
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% global user configuration for TFlab
% last updated: 13-Oct-2018 12:29:40
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% FEMbuild overwites the TFlab default
labdef.FEMbuild = 'python';
% test is a new parameter
labdef.test = 0.000000;
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% local user configuration for TFlab in the current directory
% last updated: 13-Oct-2018 12:29:50
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% nfilm overwites the TFlab default
labdef.nfilm = 6;
% test overwites the global user defined default
labdef.test = 1.000000;
% succes is a new parameter
labdef.succes = '?';
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% resulting local TFlab settings (13-Oct-2018 12:30:04):
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
labdef.expname = 'default';
labdef.nfilm = 6;
labdef.nframe = 1;
labdef.refframe = 0;
labdef.fibdef = {'iso'};
labdef.Efilm = 1.520000;
labdef.tfilm = 0.006780;
labdef.tcells = 0.002300;
labdef.FEMbuild = 'python';
labdef.nelx = 10;
labdef.nely = 20;
labdef.nelz = 1;
labdef.mininc = 0.000010;
labdef.maxinc = 1000;
labdef.nCPU = 4;
labdef.submit = 0;
labdef.curlcheck = 1;
labdef.inisigs = [0.000750, 0.001500];
labdef.cutback = 0.300000;
labdef.lesttol = 0.010000;
labdef.sigesttol = 0.000001;
labdef.simfailtol = 5;
labdef.fancyest = 0.500000;
labdef.instpath = '/home/mark/git/mylab/matlab/TFlab/';
labdef.intvars = {'refframe', 'nfilm', 'nframe', 'stack', 'curlcheck', 'simfailtol', 'maxinc', 'nelx', 'nely', 'nelz', 'nCPU', 'submit'};
labdef.TFlabUrl = 'http://mategit.wfw.wtb.tue.nl/STEM/TFlab';
labdef.TFlabBranch = 'testing';
labdef.TFlabVersion = '0.1+';
labdef.test = 1.000000;
labdef.succes = '?';
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{lstlisting}
Store this report with data and analysis script, and you'll have a pretty good WWW of the \tflab{} defaults that were active.
\section*{Some final notes}\addcontentsline{toc}{section}{\protect\numberline{\color{white}}{Some final notes}}
Do not write a local configuration script \texttt{\tflab{}\_localConfig.m} in/to the directory where you installed \tflab{}.\warning{}\\ We are not sure what might happen, if anything, but our stomachs twitch just thinking about the possibilities.
Really, if you do, you're asking for \href{http://www.imdb.com/title/tt1396484/}{it}.
Do not come whining to the hard-working developers that `it bruk'.
We warned you.
There is even an exclamation mark in the margin.\\
\noindent \tflab{}s configuration scripts allow you add your own \texttt{'name', value}-pairs to the existing defaults (e.g.\ \texttt{'test'} and \texttt{'succes'} in the report example, section \ref{repwrite}).
However, if you try to add the new default \texttt{purge = 1} to your local configuration script:
\begin{lstlisting}[language=tflab]
>> TF_labconfig('purge', 1, 'add', 'local');
\end{lstlisting}
You will be left without said configuration script.
So these \texttt{'names'} are of course \textcolor{red}{reserved} for \TF{labconfig}, in any permutation of capitalisation possible or imaginable: \textcolor{red}{\texttt{'purge'}}, \textcolor{red}{\texttt{'write'}}, \textcolor{red}{\texttt{'add'}}, \textcolor{red}{\texttt{'delete'}}, \textcolor{red}{\texttt{'report'}}, \textcolor{red}{\texttt{'local'}}, \textcolor{red}{\texttt{'global'}}, \warning\textcolor{red}{\texttt{'all'}}, and anything containing \textcolor{red}{\texttt{\tflab{}}}.\\
\noindent Allowed formats for a \texttt{value} for a parameter are: numeric (1D, 2D), \href{https://www.mathworks.com/help/matlab/ref/char.html}{char} (string), or a \href{https://www.mathworks.com/help/matlab/ref/cellstr.html}{\texttt{cellstr}} (`cell array of strings'). \TF{labconfig} does not parse, e.g., structures\footnote{we have a life, you know.}.\\
\noindent Other than that: the world is yours. You could even use \TF{labconfig} for management of default settings utterly unrelated to \tflab{}, if you were so inclined.
If you are, and you do: let us know?
We love it when our tools find new applications.
% Encoding: UTF-8
@Article{Grosberg2011,
author = {Grosberg, Anna and Alford, Patrick W. and McCain, Megan L. and Parker, Kevin Kit},
title = {{E}nsembles of engineered cardiac tissues for physiological and pharmacological study: {H}eart on a chip},
journal = {Lab Chip},