libpsdxx [WP]: fill initial file population with reasonable content

src/libs/libpsdxx/COPYING

@@ -3,4 +3,25 @@ this is <COPYING>
 LIBPSDXX - compute (cross) power spectral density
 -------------------------------------------------
 
+Copyright (c) 2019 by Thomas Forbriger
+
+The source code in this directory is part of libpsdxx which compiles to
+libpsdxx.a
+
+----
+libpsdxx is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version. 
+
+libpsdxx is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+----
+
 ----- END OF COPYING ----- 

src/libs/libpsdxx/Makefile

@@ -4,17 +4,102 @@
 # Copyright (c) 2019 by Thomas Forbriger (BFO Schiltach) 
 # 
 # create library for power spectral density analysis (libpsdxx)
+#
+# ----
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version. 
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
 # 
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+# ----
+#
 # REVISIONS and CHANGES 
 #    01/01/2019   V1.0   Thomas Forbriger
 # 
 # ============================================================================
 #
 
-all:
+.PHONY: all
+all: install doxydoc
+
+.PHONY: doc
+doc: doxydoc
+
+LIBRARIES=libpsdxx.a
+
+.PHONY: install
+install: $(addprefix $(LOCLIBDIR)/,$(LIBRARIES))
+$(LOCLIBDIR)/%: install-include %
+	mkdir -pv $(LOCLIBDIR)
+	/bin/mv -fv $(word 2,$^) $(LOCLIBDIR)
+
+# ============================================================================
+# select groups of files 
+# they are used for editing and to create object file lists and dependencies
+
+# whereever we find a README, we will use it
+README=$(filter-out %.bak,$(shell find . -name README\*))
+# the frame of doxygen documentation is palced in text files
+DOXYTXT=$(shell find . -name doxygen\*.txt)
+# C++ and C source code
+SOURCEFILES=$(filter-out %usage.h, $(filter-out %usage.cc, \
+		$(wildcard *.h *.cc *.c)))
+# editional files to be edited
+EDITFILES=Makefile $(README) \
+	    $(DOXYTXT) \
+	    $(SOURCEFILES) \
+	    $(wildcard *.cfg) \
+	    COPYING
+# ============================================================================
+# check for settings expected in the environment
+# ----------------------------------------------
+#
+CHECKVAR=$(if $($(1)),,$(error ERROR: missing variable $(1)))
+CHECKVARS=$(foreach var,$(1),$(call CHECKVAR,$(var)))
+#
+
+$(call CHECKVARS,LOCINCLUDEDIR LOCLIBDIR LOCBINDIR)
+$(call CHECKVARS,TF_BROWSER TF_WWWBASEDIR)
 
-flist: Makefile
-	echo $^ | tr ' ' '\n' | sort > $@
+# ======================================================================
+#
+LIBHEADERS=$(wildcard *.h)
+
+LIBCCSRC=$(wildcard *.cc)
+
+INCINSTALLPATH=$(LOCINCLUDEDIR)/psdxx
+LIBINSTALLPATH=$(LOCLIBDIR)
+
+# name of installed (exported) header files
+INSTHEADER=$(addprefix $(INCINSTALLPATH)/,$(notdir $(LIBHEADERS)))
+
+#
+# compiler flags
+# --------------
+
+FLAGS=
+FLAGS+=-fPIC $(MYFLAGS)
+CXXFLAGS+=-Wall $(FLAGS)
+LDFLAGS+=-L$(LOCLIBDIR)
+CPPFLAGS+=-I$(LOCINCLUDEDIR) $(FLAGS)
+# 
+# source code editing and directory clean-up
+# ------------------------------------------
+
+flist: $(EDITFILES) $(TF_EDIT)
+	echo $(filter-out $(SOURCEFILES),$(EDITFILES)) \
+	  | tr ' ' '\n' | sort > $@
+	echo '----' >> $@
+	echo $(SOURCEFILES) | tr ' ' '\n' | sort >> $@
+	echo '----' >> $@
+	echo $(TF_EDIT) | tr ' ' '\n' | sort >> $@
 
 .PHONY: edit
 edit: flist; vim $<
@@ -22,7 +107,138 @@ edit: flist; vim $<
 .PHONY: clean
 clean: ; 
 	-find . -name \*.bak | xargs --no-run-if-empty /bin/rm -v
-	-/bin/rm -vf flist
+	-find . -name \*.o | xargs --no-run-if-empty /bin/rm -v
+	-find . -name \*.d | xargs --no-run-if-empty /bin/rm -v
+	-find . -name \*.hd | xargs --no-run-if-empty /bin/rm -v
+	-/bin/rm -vf flist *.a *.so *.xxx $(TESTCBIN) $(TESTCCBIN)
+	-/bin/rm -fv $(patsubst %.txt,%.h,$(USAGEFILES))
+	-/bin/rm -fv $(patsubst %.txt,%.cc,$(USAGEFILES))
+
+#======================================================================
+# pattern rules
+# -------------
+
+%.d: %.cc
+	$(SHELL) -ec '$(CXX) -M $(CPPFLAGS) $< \
+      | sed '\''s,\($(notdir $*)\)\.o[ :]*,$(dir $@)\1.o $@ : ,g'\'' \
+        > $@; \
+      [ -s $@ ] || rm -f $@'
+
+%.d: %.c
+	$(SHELL) -ec '$(CC) -M $(CPPFLAGS) $< \
+      | sed '\''s,\($(notdir $*)\)\.o[ :]*,$(dir $@)\1.o $@ : ,g'\'' \
+        > $@; \
+      [ -s $@ ] || rm -f $@'
+
+#======================================================================
+# library part
+# ------------
+
+include $(patsubst %.cc,%.d,$(LIBCCSRC)) 
+
+libpsdxx.a: $(patsubst %.cc,%.o,$(LIBCCSRC)) 
+	ar rcv $@ $^
+	ranlib $@
+
+#----------------------------------------------------------------------
+
+$(INCINSTALLPATH)/%.h: %.h
+	mkdir -p $(INCINSTALLPATH)
+	-rm -fv $@
+	/bin/cp -vpd $< $@
+
+.PHONY: install-include
+install-include: $(INSTHEADER)
+
+#======================================================================
+# reinstall target
+# is necessary in case of header file problems (e.g. remcmmnt not installed)
+.PHONY: clean-include
+clean-include: 
+	/bin/rm -fv $(INSTHEADER)
+
+.PHONY: reinstall
+reinstall:
+	$(MAKE) clean
+	$(MAKE) clean-include
+	$(MAKE) install
+
+
+# ======================================================================
+# source code generators
+# ======================
+#
+# description and online texts
+# ----------------------------
+#  The following rules convert ordinary ASCII text files into C++ source code,
+#  providing functions to output usage information (online help)
+#
+#  Such text files use names with the pattern *usage.txt
+#  Automatically generated source code is excluded from editing and versioning
+#
+%usage.cc %usage.h: usage/%usage.txt
+	echo "// DO NOT EDIT: this file is automatically derived from $<" \
+	  > $(patsubst usage/%.txt,%.h,$<)
+	echo "extern char $(patsubst usage/%.txt,%,$<)[];" \
+	  >> $(patsubst usage/%.txt,%.h,$<)
+	echo "// DO NOT EDIT: this file is automatically derived from $<" \
+	  > $(patsubst usage/%.txt,%.cc,$<)
+	echo "#include \"$(patsubst usage/%.txt,%.h,$<)\"" \
+	  >> $(patsubst usage/%.txt,%.cc,$<)
+	echo "char $(patsubst usage/%.txt,%,$<)[]=" \
+	  >> $(patsubst usage/%.txt,%.cc,$<)
+	echo "{" >> $(patsubst usage/%.txt,%.cc,$<)
+	cat $< | egrep -v '^#' | sed -e 's/\\/\\\\/g' | sed -e 's/"/\\"/g' \
+	  | sed -e 's/$$/\\n"/' | sed -e 's/^/  "/'\
+	  >> $(patsubst usage/%.txt,%.cc,$<)
+	echo "};" >> $(patsubst usage/%.txt,%.cc,$<)
+
+#======================================================================
+# documentation part
+# ------------------
+#
+# targets commonly used:
+# ----------------------
+#
+# make doxyclean        removes all documentation
+# make doxydoc          creates doxygen documentation in the DOXYWWWPATH
+# make doxyview         creates doxygen documentation and launches netscape to
+#                       browse in the documentation
+# make doxyconf         edit the doxygen configuration file
+#
+# If you launch "make doxydoc" the documentation will be written to
+# DOXYWWWPATH (see below). This is meant to export the documentation through
+# your homepage. The doxyfull directory is just a symbolic link to this
+# directory.
+#
+
+$(call CHECKVARS,TF_WWWBASEDIR TF_BROWSER)
+
+DOXYWWWPATH=$(TF_WWWBASEDIR)/libpsdxx
+
+.PHONY: doxyclean doxyview doxydoc doxyconf
+
+doxyclean: ;/bin/rm -rfv $(DOXYWWWPATH) doxydoc.xxx
+
+DOXYSRC=$(DOXYTXT) $(LIBCCSRC) $(LIBHEADERS)\
+	  $(TESTCCSRC) Makefile
+
+PWD=$(shell env pwd)
+# create doxygen intermediate configuration
+doxydoc.xxx: doxydoc.cfg
+	sed 's,<OUTPUTDIRECTORY>,$(DOXYWWWPATH),g;s,<STRIPFROMPATH>,$(PWD),g' \
+	  $< > $@
+# create commented version of doxygen configuration
+doxycomm.xxx: doxydoc.cfg
+	/bin/cp -vf $< $@; doxygen -u $@
+
+$(DOXYWWWPATH)/html/index.html: doxydoc.xxx $(DOXYSRC)
+	mkdir -vp $(DOXYWWWPATH)
+	doxygen $<
+
+doxydoc: $(DOXYWWWPATH)/html/index.html
 
+doxyview: $(DOXYWWWPATH)/html/index.html
+	$(TF_BROWSER) file:$< &
 
 # ----- END OF Makefile ----- 

src/libs/libpsdxx/README

@@ -3,4 +3,47 @@ this is <README>
 LIBPSDXX - compute (cross) power spectral density
 -------------------------------------------------
 
+Purpose
+-------
+Compute cross power spectral density and power spectral density.
+
+Description
+-----------
+This library (libpsdxx) provides a C++ class to compute the cross power
+spectral density of two time series, the power spectral density of a single
+time series and the coherency of two time series.
+
+Documentation
+=============
+doxygen source code documentation
+---------------------------------
+Detailed documentation of concept and implementation is provided in the source
+code. doxygen can be used to create appropriate html files. See target
+doxydoc in the Makefile. The libraries API is described there.
+
+Introductory texts are provided in doxygen.txt and are used in the doxygen
+documentation.
+
+Installation
+============
+See README.md and INSTALL.md in the root directory of the repository for
+general installation instructions.
+
+environment variables:
+  LOCINCLUDEDIR   Defines the path where header files will be copied for
+                  usage in your own projects. You will pass this path to
+                  the precompiler with the -I option.
+  LOCLIBDIR       Defines the path where the binary library will be
+                  placed.
+  TF_WWWBASEDIR   Defines the path to your personal homepage. That's the
+                  place where doxygen output will be written too (see
+                  in the Makefile).
+
+make all             installs headers, binary libraries and documentation
+
+Dependencies
+------------
+This library requires code from libaff, libtsxx, libfourierxx.
+An external dependency is fftw3
+
 ----- END OF README ----- 

src/libs/libpsdxx/debug.h

@@ -25,19 +25,19 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  * ----
- *
  * 
  * REVISIONS and CHANGES 
  *  - 05/05/2011   V1.0   Thomas Forbriger
+ *  - 01/01/2019   V1.1   copied from libstfinv
  * 
  * ============================================================================
  */
 
 // include guard
-#ifndef STFINV_DEBUG_H_VERSION
+#ifndef PSDXX_DEBUG_H_VERSION
 
-#define STFINV_DEBUG_H_VERSION \
-  "STFINV_DEBUG_H   V1.0"
+#define PSDXX_DEBUG_H_VERSION \
+  "PSDXX_DEBUG_H   V1.1"
 
 /*! \brief produce debug output
  * \ingroup group_debug
@@ -46,7 +46,7 @@
  * \param N name of function 
  * \param M message to print
  */
-#define STFINV_debug(C,N,M) \
+#define PSDXX_debug(C,N,M) \
   if (C) { \
     std::cerr << "DEBUG (" << N << ", " \
       << __FILE__ << " line #" << __LINE__ << "):" << std::endl \
@@ -59,18 +59,18 @@
  *
  * \param P parameter to dump
  */
-#define STFINV_value( P ) #P << "=" << P
+#define PSDXX_value( P ) #P << "=" << P
 
 /*! \brief report value of expression
  * \ingroup group_debug
  *
  * \param P parameter to dump
  */
-#define STFINV_DUMP( P ) \
+#define PSDXX_DUMP( P ) \
   std::cerr << "DEBUG: " \
     << __FILE__ << " line #" << __LINE__ << " " \
     << #P << "=" << P << std::endl;
 
-#endif // STFINV_DEBUG_H_VERSION (includeguard)
+#endif // PSDXX_DEBUG_H_VERSION (includeguard)
 
 /* ----- END OF debug.h ----- */

src/libs/libpsdxx/doxygen.txt

+/*! \file doxygen.txt
+ * \brief PSDXX library: compute (cross) power spectral density (prototypes)
+ * 
+ * ----------------------------------------------------------------------------
+ * 
+ * \author Thomas Forbriger
+ * \date 01/01/2019
+ * 
+ * PSDXX library: compute (cross) power spectral density (prototypes)
+ * 
+ * Copyright (c) 2019 by Thomas Forbriger (BFO Schiltach) 
+ *
+ * The source code in this directory is part of libpsdxx which compiles to
+ * libpsdxx.a
+ *
+ * ----
+ * libpsdxx is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version. 
+ * 
+ * libpsdxx is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ * ----
+ * 
+ * REVISIONS and CHANGES 
+ *  - 01/01/2019   V1.0   Thomas Forbriger
+ * 
+ * ============================================================================
+ */
+
+/*! \brief Root namespace of library
+  
+ */
+namespace psd {
+} // namespace psd
+
+/*======================================================================*/
+
+/*! \mainpage
+
+\author Thomas Forbriger
+\since January 2019
+\date January 2019
+\version V1.0
+
+\par Purpose
+Compute cross power spectral density and power spectral density.
+
+\par Description
+This library (libpsdxx) provides a C++ class to compute the cross power
+spectral density of two time series, the power spectral density of a single
+time series and the coherency of two time series.
+
+\date 01.01.2019
+
+/* ----- END OF doxygen.txt ----- */

src/libs/libpsdxx/doxygen.txt.h

-/*! \file doxygen.txt.h
- * \brief PSDXX library: compute (cross) power spectral density (prototypes)
- * 
- * ----------------------------------------------------------------------------
- * 
- * \author Thomas Forbriger
- * \date 01/01/2019
- * 
- * PSDXX library: compute (cross) power spectral density (prototypes)
- * 
- * Copyright (c) 2019 by Thomas Forbriger (BFO Schiltach) 
- * 
- * REVISIONS and CHANGES 
- *  - 01/01/2019   V1.0   Thomas Forbriger
- * 
- * ============================================================================
- */
-
-// include guard
-#ifndef TF_DOXYGEN_TXT_H_VERSION
-
-#define TF_DOXYGEN_TXT_H_VERSION \
-  "TF_DOXYGEN_TXT_H   V1.0   "
-
-namespace tf {
-
-}
-
-#endif // TF_DOXYGEN_TXT_H_VERSION (includeguard)
-
-/* ----- END OF doxygen.txt.h ----- */

src/libs/libpsdxx/error.cc

@@ -25,15 +25,15 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  * ----
- *
  * 
  * REVISIONS and CHANGES 
  *  - 05/05/2011   V1.0   Thomas Forbriger
+ *  - 01/01/2019   V1.1   copied from libstfinv
  * 
  * ============================================================================
  */
-#define STFINV_ERROR_CC_VERSION \
-  "STFINV_ERROR_CC   V1.0"
+#define PSDXX_ERROR_CC_VERSION \
+  "PSDXX_ERROR_CC   V1.1"
 
 #include <iostream>
 #include <stfinv/error.h>

src/libs/libpsdxx/error.h

@@ -25,19 +25,19 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  * ----
- *
  * 
  * REVISIONS and CHANGES 
  *  - 05/05/2011   V1.0   Thomas Forbriger
+ *  - 01/01/2019   V1.1   copied from libstfinv
  * 
  * ============================================================================
  */
 
 // include guard
-#ifndef STFINV_ERROR_H_VERSION
+#ifndef PSDXX_ERROR_H_VERSION
 
-#define STFINV_ERROR_H_VERSION \
-  "STFINV_ERROR_H   V1.0"
+#define PSDXX_ERROR_H_VERSION \
+  "PSDXX_ERROR_H   V1.1"
 
 #include <iostream>
 
@@ -54,9 +54,9 @@ namespace stfinv {
    * initialization. If you don't like this, call dont_report_on_construct().
    *
    * \ingroup group_error
-   * \sa STFINV_Xassert
-   * \sa STFINV_assert
-   * \sa STFINV_abort
+   * \sa PSDXX_Xassert
+   * \sa PSDXX_assert
+   * \sa PSDXX_abort
    */
   class Exception 
   {
@@ -128,7 +128,7 @@ namespace stfinv {
  * \param M message of type char*
  * \param E exception class to throw
  */
-#define STFINV_Xassert(C,M,E) \
+#define PSDXX_Xassert(C,M,E) \
   if (!(C)) { throw( E ( M , __FILE__, __LINE__, #C )); }
 
 /*! \brief Check an assertion and report by throwing an exception.
@@ -137,21 +137,21 @@ namespace stfinv {
  * \param C assert condition
  * \param M message of type char*
  */
-#define STFINV_assert(C,M) STFINV_Xassert( C , M , stfinv::Exception )
+#define PSDXX_assert(C,M) PSDXX_Xassert( C , M , stfinv::Exception )
 
 /*! \brief Abort and give a message.
  *
  * \ingroup group_error
  * \param M message of type char*
  */
-#define STFINV_abort(M) \
+#define PSDXX_abort(M) \
   throw( stfinv::Exception ( M , __FILE__, __LINE__ )) 
 
 /*! \brief Abort if function is called illegally.
  * 
  * \ingroup group_error
  */
-#define STFINV_illegal STFINV_abort("illegal call!")
+#define PSDXX_illegal PSDXX_abort("illegal call!")
 
 /*! \brief Check an assertion and report only.
  *
@@ -161,7 +161,7 @@ namespace stfinv {
  * \param V any values that should be output (comment)
  *          a sequence of values and output operators
  */
-#define STFINV_report_assert(C,M,V) \
+#define PSDXX_report_assert(C,M,V) \
   if (!(C)) { \
     stfinv::report_violation(M, __FILE__, __LINE__, #C); \
     std::cerr << "* comment: " << V << std::endl; \
@@ -178,9 +178,9 @@ namespace stfinv {
  * \param V any values that should be output (comment)
  *          a sequence of values and output operators
  */
-#define STFINV_nonfatal_assert(F,C,M,V) \
-  if (F) { STFINV_report_assert(C,M,V) } else { STFINV_assert(C,M) }
+#define PSDXX_nonfatal_assert(F,C,M,V) \
+  if (F) { PSDXX_report_assert(C,M,V) } else { PSDXX_assert(C,M) }
 
-#endif // STFINV_ERROR_H_VERSION (includeguard)
+#endif // PSDXX_ERROR_H_VERSION (includeguard)
 
 /* ----- END OF error.h ----- */

src/libs/libpsdxx/psd.h

@@ -9,7 +9,22 @@
  * LIBPSDXX - compute (cross) power spectral density (prototypes)
  * 
  * Copyright (c) 2019 by Thomas Forbriger (BFO Schiltach) 
+ *
+ * ----
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version. 
  * 
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ * ----
+ *
  * REVISIONS and CHANGES 
  *  - 01/01/2019   V1.0   Thomas Forbriger
  * 
@@ -17,15 +32,15 @@
  */
 
 // include guard
-#ifndef TF_PSD_H_VERSION
+#ifndef PSDXX_PSD_H_VERSION
 
-#define TF_PSD_H_VERSION \
-  "TF_PSD_H   V1.0   "
+#define PSDXX_PSD_H_VERSION \
+  "PSDXX_PSD_H   V1.0"
 
-namespace tf {
+namespace psd {
 
-}
+} // namespace psd
 
-#endif // TF_PSD_H_VERSION (includeguard)
+#endif // PSDXX_PSD_H_VERSION (includeguard)
 
 /* ----- END OF psd.h ----- */