tutorial: lesson 1 InputNg needs recap and exercises

doc/tutorial.ptex

@@ -77,7 +77,8 @@ add or modify or improve functionality in PsimagLite itself,
 and so your solutions could be included in PsimagLite.
 You are encouraged to git clone PsimagLite and make changes that
 you think are suitable, and request pulls, and discuss in our 
-mailing list.
+mailing list. All corrections are welcomed, and either git pull
+request or emails are OK.
 
 The actual topics to be discussed will become clear once we have
 some lessons typed in. The actual .cpp programs that use and
@@ -102,7 +103,7 @@ the right name for \texttt{PartName}.
 This way we import documentation from each .cpp file
 into this ptex file.
 
-In addition to being sort, the .cpp files for the tutorial
+In addition to being short, the .cpp files for the tutorial
 should include compilation instructions without any \texttt{Makefile},
 so that all includes and library paths and compiler switches
 are visible in the command line. Dependencies must be kept
@@ -117,9 +118,13 @@ again the example should be able to compile without it; it won't run
 though, but display a message saying that the GSL is needed.
 
 \ptexPaste{InputNg_Intro}
-\begin{lstlisting}
-\ptexPaste{InputNg_Includes}
-\end{lstlisting}
+\ptexPaste{InputNg_MyInputCheck}
+\ptexPaste{InputNg_main1}
+\ptexPaste{InputNg_main2}
+\ptexPaste{InputNg_main3}
+\ptexPaste{InputNg_main4}
+\ptexPaste{InputNg_main5}
+\ptexPaste{InputNg_Recap}
 
 \end{document}
 

drivers/testInputNg.cpp

@@ -7,13 +7,13 @@
   from an input file and use them in your program.
 
   You can go ahead an compile this example with
-\begin{footnotesize}
+\begin{tiny}
 \begin{verbatim}
 g++ testInputNg.cpp -I ../src/ -I.. -DUSE_BOOST -L ../lib -lpsimaglite -o testInputNg
 \end{verbatim}
-\end{footnotesize}
+\end{tiny}
 Note that you need boost-dev or boost-devel and also you
-must have lib/PsimagLite already compiled.
+must have lib/libsimaglite.a already compiled.
 You can already go ahead an run it with the provided simple input
 \begin{verbatim}
 ./testInputNg testInput.ain
@@ -27,6 +27,9 @@ So, now let's discuss the short program we have here.
 First, note that we need two includes from PsimagLite.
 PsimagLite files are usually under src, but in some
 cases subdirectories are used. Here are the includes.
+\begin{lstlisting}
+PSIDOCCOPY InputNg_Includes
+\end{lstlisting}
 */
 
 /* PSIDOC_CODE_START InputNg_Includes nocapture */
@@ -34,6 +37,29 @@ cases subdirectories are used. Here are the includes.
 #include "InputCheckBase.h"
 /* PSIDOC_CODE_END */
 
+/* PSIDOC InputNg_MyInputCheck
+ There is an option to check the inputs, so that
+ you can define the labels that you expect to find
+ in your program. This is optional but recommended.
+ For this we create a class, say \texttt{MyInputCheck},
+ and derive it from PsimagLite's \texttt{InputCheckBase}.
+This inheritance isn't needed, but save us from
+having to provide all functions, as the base class
+implements defaults. For a more realistic use
+case you can check DMRG++'s InputCheck.h under
+dmrgpp/src/Engine. For now, here's our short
+input checking class.
+\begin{lstlisting}
+PSIDOCCOPY InputNg_Class_MyInputCheck
+\end{lstlisting}
+In our example, we are defining a scalar
+called myscalar, a vector called myvector, and
+a string called mystring. This is what we
+expect to read from the input file, even though
+the writer of the input may add other labels.
+*/
+
+/* PSIDOC_CODE_START InputNg_Class_MyInputCheck nocapture */
 class MyInputCheck : public PsimagLite::InputCheckBase {
 
 public:
@@ -46,7 +72,27 @@ public:
 		return str;
 	}
 };
+/* PSIDOC_CODE_END */
+
+/* PSIDOC InputNg_main1
+Now for the actual reading of the input file, we'll use
+\cppFile{InputNg}. We'll alias its type first with
+\begin{verbatim}
+typedef PsimagLite::InputNg<MyInputCheck> InputNgType;
+\end{verbatim}
+InputNg expects one template argument, our input checking class,
+which we have just described.
+We'll also have to use the actual name provided to this
+program, which should be in \verb!argv[1]!, which we put
+in C++ variable \texttt{filename}. We need to create an
+object of our class MyInputCheck as well.
+We then have the following code so far
+\begin{lstlisting}
+PSIDOCCOPY InputNg_main_part1
+\end{lstlisting}
+*/
 
+/* PSIDOC_CODE_START InputNg_main_part1 nocapture */
 int main(int argc, char* argv[])
 {
 	if (argc != 2) {
@@ -58,21 +104,96 @@ int main(int argc, char* argv[])
 
 	std::string filename(argv[1]);
 	MyInputCheck myInputCheck;
+/* PSIDOC_CODE_END */
+
+/* PSIDOC InputNg_main2
+We are now ready to read the file, which we do
+with the following two statements
+\begin{lstlisting}
+PSIDOCCOPY InputNg_main_part2
+\end{lstlisting}
+From now on, we can forget about the myInputCheck object,
+and the ioWriteable object as well, and consider
+only the io object, which we will use to read labels.
+The data from the file is now in memory, and the file
+does not have to be read or even present anymore.
+*/
+
+/* PSIDOC_CODE_START InputNg_main_part2 nocapture */
 	InputNgType::Writeable ioWriteable(filename, myInputCheck);
 	InputNgType::Readable io(ioWriteable);
+/* PSIDOC_CODE_END */
 
+/* PSIDOC InputNg_main3
+Let's now read some data from the file using the
+io object. (The data is now in memory, and it
+is \emph{not actually} read from the file, but we will use
+that terminology anyway.) We read the scalar first, and
+print it to the terminal with the following code.
+\begin{lstlisting}
+PSIDOCCOPY InputNg_code_main3
+\end{lstlisting}
+The first argument to io.readline will be filled
+with the value from the file that follows the
+label myscalar. Even though the value will be filled,
+it's best practice to initialize it first anyway.
+*/
+
+/* PSIDOC_CODE_START InputNg_code_main3 nocapture */
 	int myscalar = 0;
 	io.readline(myscalar, "myscalar=");
 
 	std::cout<<"I've read label myscalar with value ";
 	std::cout<<myscalar<<" from "<<io.filename()<<"\n";
+/* PSIDOC_CODE_END */
+
+/* PSIDOC InputNg_main4
+Let's now read a vector. Note that we use just
+io.read to read vectors (and matrices), whereas we
+use io.readline to read scalars. The vector will
+be resized for you as needed, so you do not need
+to size it. If you choose to size it, then Ainur
+format will be able to use ellipsis to fill the vector
+and you may be able to enter in the input file something
+like myvector=[42, ...]; which will cause your vector
+to be filled with the number 42.
+\begin{lstlisting}
+PSIDOCCOPY InputNg_code_main4
+\end{lstlisting}
+*/
+/* PSIDOC_CODE_START InputNg_code_main4 nocapture */
 	std::vector<double> v;
 	io.read(v, "myvector");
+/* PSIDOC_CODE_END */
 
-	std::string mystr;
+/* PSIDOC InputNg_main5
+The two previous examples required the labels to
+be present in the input file. But what if we want
+to have an \emph{optional} label in the input file?
+To deal with that we put the io.readline statement
+inside a try and catch block, as follows.
+\begin{lstlisting}
+PSIDOCCOPY InputNg_code_main5
+\end{lstlisting}
+This way if the user provides the label mystring
+then the C++ variable mystr will have the value
+the user provided. Otherwise, the value of mystr
+will remain ``default'', and no error will be issued.
+*/
+
+/* PSIDOC_CODE_START InputNg_code_main5 nocapture */
+	std::string mystr("default");
 	try {
 		io.readline(mystr, "mystring=");
 	} catch (std::exception&)
 	{}
 }
+/* PSIDOC_CODE_END */
 
+/* PSIDOC InputNg_Recap
+
+\subsection*{Recap}
+In this lesson we have learned, blah blah.
+
+\subsection*{Exercises}
+*/