Merge pull request #87 in VECTO/vecto-sim from...

Merge pull request #87 in VECTO/vecto-sim from ~EMQUARIMA/vecto-sim:feature/VECTO-139-prepare-for-first-beta-release to develop

* commit '2e1a03f2': (62 commits)
  update vecto comparison
  update repository
  bugfixes to make some tests work again
  finalize release report
  adding release notes pdf
  adding images and sources to generate graphs in report
  authors, screenshots unit tests, complexity
  draft version of release notes and release report
  build number
  update repo
  corrected wrong file paths in test again
  corrected local paths in declaration test
  corrected summary file writer
  graphwriter: split full cycle into smaller parts
  update repository
  more verbose logging in driver model
  more accurate distance computation in Vehicle
  switch to drive as next driving action when a halt-action is performed
  make engine-only tests run again
  add gear name property to transmission loss map for better logging
  ...

DeclarationCycleZip/App.config

+<?xml version="1.0" encoding="utf-8" ?>
+<configuration>
+    <startup> 
+        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
+    </startup>
+</configuration>
\ No newline at end of file

DeclarationCycleZip/DeclarationCycleZip.csproj

+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
+    <ProjectGuid>{2320CD6F-FE7B-4341-A9BB-3ABCA7EF18F6}</ProjectGuid>
+    <OutputType>Exe</OutputType>
+    <AppDesignerFolder>Properties</AppDesignerFolder>
+    <RootNamespace>DeclarationCycleZip</RootNamespace>
+    <AssemblyName>DeclarationCycleZip</AssemblyName>
+    <TargetFrameworkVersion>v4.5</TargetFrameworkVersion>
+    <FileAlignment>512</FileAlignment>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
+    <PlatformTarget>AnyCPU</PlatformTarget>
+    <DebugSymbols>true</DebugSymbols>
+    <DebugType>full</DebugType>
+    <Optimize>false</Optimize>
+    <OutputPath>bin\Debug\</OutputPath>
+    <DefineConstants>DEBUG;TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
+    <PlatformTarget>AnyCPU</PlatformTarget>
+    <DebugType>pdbonly</DebugType>
+    <Optimize>true</Optimize>
+    <OutputPath>bin\Release\</OutputPath>
+    <DefineConstants>TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+  </PropertyGroup>
+  <ItemGroup>
+    <Reference Include="System" />
+    <Reference Include="System.Core" />
+    <Reference Include="System.Xml.Linq" />
+    <Reference Include="System.Data.DataSetExtensions" />
+    <Reference Include="Microsoft.CSharp" />
+    <Reference Include="System.Data" />
+    <Reference Include="System.Xml" />
+  </ItemGroup>
+  <ItemGroup>
+    <Compile Include="Program.cs" />
+    <Compile Include="Properties\AssemblyInfo.cs" />
+  </ItemGroup>
+  <ItemGroup>
+    <None Include="App.config" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\VectoCore\VectoCore.csproj">
+      <Project>{CD36938A-ADD9-4C65-96DA-B397CDEEA90A}</Project>
+      <Name>VectoCore</Name>
+    </ProjectReference>
+  </ItemGroup>
+  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
+  <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 
+       Other similar extension points exist, see Microsoft.Common.targets.
+  <Target Name="BeforeBuild">
+  </Target>
+  <Target Name="AfterBuild">
+  </Target>
+  -->
+</Project>
\ No newline at end of file

DeclarationCycleZip/Program.cs

+using System;
+using System.Collections.Generic;
+using System.Data;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using TUGraz.VectoCore.FileIO.Reader;
+using TUGraz.VectoCore.Utils;
+
+namespace DeclarationCycleZip
+{
+	internal class Program
+	{
+		private static void Main(string[] args)
+		{
+			var cycleData = DrivingCycleDataReader.ReadFromFileDistanceBased(args[0]);
+
+			var table = new DataTable();
+			table.Columns.Add("<s>");
+			table.Columns.Add("<v>");
+			table.Columns.Add("<grad>");
+			table.Columns.Add("<stop>");
+
+			var lastDistance = cycleData.Entries.First().Distance - 1.SI<Meter>();
+			foreach (var x in cycleData.Entries) {
+				if (x.Distance.IsEqual(lastDistance)) {
+					continue;
+				}
+				var row = table.NewRow();
+				row["<s>"] = x.Distance.Value().ToString(CultureInfo.InvariantCulture);
+				row["<v>"] = x.VehicleTargetSpeed.ConvertTo().Kilo.Meter.Per.Hour.Value().ToString(CultureInfo.InvariantCulture);
+				row["<grad>"] = x.RoadGradientPercent.ToString(CultureInfo.InvariantCulture);
+				row["<stop>"] = x.StoppingTime.Value().ToString(CultureInfo.InvariantCulture);
+				table.Rows.Add(row);
+				lastDistance = x.Distance;
+			}
+
+			VectoCSVFile.Write(Path.GetFileName(args[0]), table);
+		}
+	}
+}
\ No newline at end of file

DeclarationCycleZip/Properties/AssemblyInfo.cs

+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+// General Information about an assembly is controlled through the following 
+// set of attributes. Change these attribute values to modify the information
+// associated with an assembly.
+[assembly: AssemblyTitle("DeclarationCycleZip")]
+[assembly: AssemblyDescription("")]
+[assembly: AssemblyConfiguration("")]
+[assembly: AssemblyCompany("")]
+[assembly: AssemblyProduct("DeclarationCycleZip")]
+[assembly: AssemblyCopyright("Copyright ©  2015")]
+[assembly: AssemblyTrademark("")]
+[assembly: AssemblyCulture("")]
+
+// Setting ComVisible to false makes the types in this assembly not visible 
+// to COM components.  If you need to access a type in this assembly from 
+// COM, set the ComVisible attribute to true on that type.
+[assembly: ComVisible(false)]
+
+// The following GUID is for the ID of the typelib if this project is exposed to COM
+[assembly: Guid("b8f01491-78a5-4d78-a575-3e6d1eed6e7e")]
+
+// Version information for an assembly consists of the following four values:
+//
+//      Major Version
+//      Minor Version 
+//      Build Number
+//      Revision
+//
+// You can specify all the values or you can default the Build and Revision Numbers 
+// by using the '*' as shown below:
+// [assembly: AssemblyVersion("1.0.*")]
+[assembly: AssemblyVersion("1.0.0.0")]
+[assembly: AssemblyFileVersion("1.0.0.0")]

Documentation/ReleaseNotes/ReleaseNotes.tex

+
+\input{preamble_handout}
+
+% \includeonlylecture{lecture_0}
+
+\input{content}
+
+%% EOF

Documentation/ReleaseNotes/ReleaseReport.tex

+\input{preamble_handout}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{document}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% \titleframe
+\title{Vecto 3.0.1 Release Report}	% Kurztitel in []
+
+\maketitle
+
+%====================
+
+\input{Vecto_3.0.1.312/ReleaseNotes.tex}
+
+\input{Vecto_3.0.1.312/Comparison.tex}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\end{document}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Documentation/ReleaseNotes/Vecto_3.0.1.312/ReleaseNotes.tex

+%!TEX root = ../ReleaseNotes.tex
+
+
+% %----------------------------
+
+% \begin{frame}[t]\frametitle{Usage -- GUI}
+% 	\tskipl
+%     \begin{itemize}
+%     	\item Vecto 3 has been integrated in the GUI of Vecto 2.2
+%     	\item Separate ``Start'' Button for Vecto 3
+%     \end{itemize}
+% \begin{center}
+% 	\includegraphics[width=\textwidth]{Vecto3_0_1_UI.png}
+% \end{center}
+% \end{frame}
+
+% \begin{frame}[t]\frametitle{Usage -- Command Line}
+%     \tskipl
+%     \begin{itemize}
+%     	\item Vecto 3 can also be started from the command line
+%     	\item Type ``vectocmd.exe -h'' for usage instructions
+%     \end{itemize}
+% \begin{center}
+% 	\includegraphics[width=\textwidth]{Vecto3_0_1_cmd.png}
+% \end{center}
+
+% \end{frame}
+
+% %----------------------------
+
+% \begin{frame}[t,allowframebreaks]{Changes in Vecto 3.0.1}
+% 	\tskipl
+% 	\begin{itemize}
+% 		\item Vecto 3.0 is written from scratch
+% 		\begin{itemize}
+% 			\item Windows DLL written in C\#
+% 			\item Modular software architecture
+% 			\item Distance-based simulation
+% 		\end{itemize}
+% 	\end{itemize}
+
+% \end{frame}
+
+
+\section{Vecto 3.0.1 Release Notes}
+
+%-------------------------------------------------------------------------
+\subsection{General Notes} % (fold)
+\label{ssub:general_notes}
+%-------------------------------------------------------------------------
+
+Vecto 3.0 has been rewritten from scratch. It is now a dynamic program library that contains the core simulation and can be embedded in other applications.
+
+
+Vecto 3.0.1 has been integrated in the graphical user interface of Vecto 2.2 via an additional ``Start'' button on the main screen (cf.~\Cref{fig:Vecto3_GUI}). Additionally, a command-line program is provided to run multiple Vecto jobs (cf.~\Cref{fig:Vecto3_CMD}). For more information how to use the command-line program please see ``vectocmd.exe - h''.\\[-0.3em]
+
+In case you find a bug or Vecto 3.0 does not behave as expected \textbf{please follow the instructions} given in \Cref{sec:how_to_submit_a_bug_report}.
+
+\begin{figure}
+	\centering
+	\includegraphics[width=0.6\textwidth]{img/Vecto3_0_1_UI.png}
+	\caption{Vecto 3.0.1 Graphical User Interface}
+	\label{fig:Vecto3_GUI}
+\end{figure}
+
+\begin{figure}
+	\centering
+	\includegraphics[width=0.6\textwidth]{img/Vecto3_0_1_cmd.png}
+	\caption{Vecto 3.0.1 Command Line Program}
+	\label{fig:Vecto3_CMD}
+\end{figure}
+
+%-------------------------------------------------------------------------
+\subsection{Changes in Vecto 3.0.1} % (fold)
+\label{ssub:changes_in_vecto_3_0_1}
+%-------------------------------------------------------------------------
+
+\begin{itemize}
+	\item New distance-based simulation model
+	\item Simulation with variable steps. The simulation distance is adapted such that the respective time is about 0.5\,s (parameter \textsc{TargetTimeInterval}). Certain simulation events are calculated using adapted time intervals (e.g. for traction interruption or to exactly meet the target speed vs. distance cycle).
+	\item Accuracy of simulated distance vs. driving cycle distance $< 1\,\mu\textrm{m}$
+	\item New component-based software architecture
+	\begin{itemize}
+		\item Separate software component for every part of the power-train:
+		Combustion Engine,
+		Clutch,
+		Gearbox,
+		Retarder,
+		Axle Gear
+		Vehicle,
+		Wheels,
+		Driver,
+		Driving Cycle
+
+		The models of every component are taken from Vecto 2.2
+		\item Interfaces for components reflecting physical quantities:
+		force/velocity, angular speed/torque, \ldots
+		\item Power-train components modularly usable, custom power-train configurations possible
+	\end{itemize}
+	\item \textsc{DriverStrategy} as separate component with well-defined interface
+	\item \textsc{GearshiftStrategy} as separate component with well-defined interface
+	\item All computations are done in SI units; data-types reflect concrete SI units (i.e., kg, m, s, Nm, \ldots)
+	\item Run-time conformity check of SI units on all computations and SI conversions. (might be relaxed for final relase version)
+	\item Traction interruption of arbitrary time possible (also $<$ 1\,s), accurate simulation of traction interruption time
+	\item New \textsc{Idle-Controller} to simulate engine speed during traction interruption periods
+	\item Intelligent search of operating point during coasting, braking, and in engine-overload situations, deviation from FLD $<$ 0.5\,W (parameter \textsc{EnginePowerSearchTolerance}).
+	\item Exact analytic solutions instead of exhaustive search where possible, e.g., computing engine's preferred speed, computing time interval required for driving a certain distance, compute distance required to decelerate to a given target speed depending on the driver's deceleration curve, computation of distance to drive when accelerating before braking, \ldots
+	\item Support sparse representation of driving cycles. Instead of specifying the driving cycle on a per-meter basis only distance entries with speed or slope changes need to be specified. Reduction of 96\,\% in disk space
+	\item Multi-threaded execution when multiple driving cycles resp. multiple Vecto jobs are executed
+	\item Vecto 3.0.1 only supports the latest version of the input file formats (JSON), i.e., .vecto: v\,2; .vveh: v\,7; .vgbx: v\,5; .veng: v\,3
+	\item Support for arbitrary order of columns in CSV files if the header is given as specified in the Manual. If the header is not recognized: fall-back to column-based parsing
+	\item more energy-efficient implementation of \textit{Overspeed}: vehicle acceleration only due to road's slope, engine is on drag-curve
+	\item Use of well-known logging framework (NLog) allows to configure logging output based on severity and namespace. Supports different logging targets
+	\item Implemented in C\#, requires .Net Framework version 4.5
+	\item Use of latest libraries for logging, parsing JSON files, and processing of PDF files
+	\item 270 unit- and integration-tests developed; 262 tests passed by Vecto release; 4 tests failed due to unreasonable vehicle configuration (torque outside loss-map range), 4 tests failed due to unreasonable driving cycles (15\,\% and 25\,\% uphill)
+	%Software Tests: 258 successful unit- and integration tests
+	\begin{itemize}
+		\item Code coverage: 84\,\% \\
+		The main parts of the code are covered by tests, parts with low coverage are mainly auto-generated equality methods and parsing of input data (cf.~\Cref{fig:Vecto301_TestCoverage})
+	\end{itemize}
+	\item Code complexity\footnote{According to \textit{SourceMonitor}}: currently the max. complexity is 20 (single method) and 10 methods have a complexity $>$10. The most complex methods are in the ShiftStrategy, the DriverStrategy, and the Powertrain builder; see \Cref{fig:Vecto301_Komplexity}.% and \Cref{fig:Vecto301_Kiviat}
+\end{itemize}
+
+\begin{figure}
+	\centering
+	\includegraphics[width=0.8\textwidth]{img/Vecto3_0_1_TestCoverage.png}
+	\caption{Screenshot of Test-coverage Report (Microsoft Visual Studio)}
+	\label{fig:Vecto301_TestCoverage}
+\end{figure}
+
+\begin{figure}
+	\centering
+	\includegraphics[width=0.6\textwidth]{img/Vecto3_0_1-Checkpoints.png}\\[1cm]
+
+	\includegraphics[width=0.6\textwidth]{img/Vecto3_0_1-ClassComplexity.png}\\[1cm]
+
+	\includegraphics[width=0.6\textwidth]{img/Vecto3_0_1-MethodComplexity.png}
+
+	\caption{Screenshots of code metrics (SourceMonitor): Checkpoints over time (top), list of classes sorted by complexity (middle), List of methods sorted by complexity (bottom)}
+	\label{fig:Vecto301_Komplexity}
+\end{figure}
+
+% \begin{figure}
+% 	\centering
+
+% 	\includegraphics[width=0.6\textwidth]{img/Vecto3_0_1-Kiviat.png}
+% 	\caption{Kiviat Metrics Graph (SourceMonitor)}
+% 	\label{fig:Vecto301_Kiviat}
+% \end{figure}
+
+
+%=========================================================================
+\subsection{Open Issues} % (fold)
+\label{sub:open_issues}
+%=========================================================================
+
+\begin{itemize}
+	\item Sanity checks on input data
+	\item Refactoring of DefaultDriverStrategy to handle certain situations when braking is required during coasting to meet small target-speed changes during coasting.
+	\item Status output to GUI/Console during simulation
+	\item Advanced Driver Assist Systems
+	\item Adaptation of component models to most recent ACEA Whitebook
+\end{itemize}
+
+% subsection open_issues (end)
+
+\FloatBarrier
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{How to Submit a Bug Report} % (fold)
+\label{sec:how_to_submit_a_bug_report}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+In case you encounter a bug or Vecto~3 is not behaving as you would expect it is of utmost importance that the developers can reproduce your results\footnote{\url{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}}. All bugs should be submitted as Jira Issue (either \textit{Bug} or \textit{Feature}/\textit{Task}) to maintain traceability. \\[0.5em]
+
+Every bug-report should contain a detailed description containing:
+\begin{itemize}
+	\item What did you do
+	\item What is your expected outcome
+	\item What is the actual outcome
+	\item Which Vecto version did you use? (Version number and Build number) \\
+		The version number is printed when you start vectocmd in verbose mode
+	\item Screenshots if necessary
+\end{itemize}
+
+In addition a detailed log of your simulation is necessary. Please follow these instruction to create a log-file and the mod-files:
+
+\begin{itemize}
+	\item \textbf{Start a command-line}\\
+		Press \textit{Windows-r} and type \texttt{cmd}, change to the directory where you extracted Vecto 3.0
+	\item Delete old log-files:\\
+		\texttt{del logs\textbackslash*}
+	\item Start the simulation using Vecto-Commandline: \\
+		\texttt{vectocmd.exe -t -vvvv -mod $<$jobfile.vecto$>$} \\
+		it is important to use  the option \texttt{-vvvv} and \texttt{-mod} which enable verbose logging and output of the mod-data file (\texttt{.vmod}. \\[0.5em]
+		If logging is enabled, the simulation runs are executed sequentially. If the error occurs only in some simulation runs (i.e., driving cycle and loading) you can cancel the other simulation runs by pressing \textit{Ctrl-c}. (Note: if verbose logging is enabled the simulation takes much longer)
+	\item File a new Jira issue\footnote{\url{https://webgate.ec.europa.eu/CITnet/jira/secure/CreateIssue!default.jspa}} with a detailed description (see above)
+	\item Attach all data necessary to reproduce your results to the Jira issue, or if the data is confidential you can directly send it to the developers.
+	\begin{itemize}
+		\item All input files
+		\item All Log-files in the directory \texttt{logs} (compressed)
+		\item Mod-files (stored in the directory of the Vecto job)
+	\end{itemize}
+\end{itemize}
+
+% - use jira
+% - cmdline, ctrl-c
+% - enable verbose logging (Debug)
+% - clean logs
+% - send input data (all), mod-files, logs, exact version number, expected behavior vs. actual output/result
+
+% section how_to_submit_a_bug_report (end)
+
+