Merged in dev (pull request #84)

Final release - v1.0.1

Approved-by: Benjamin Bowers
Approved-by: Dylan
Approved-by: Zak Booth

README.md

@@ -39,7 +39,8 @@ Please see the sections below for detailed instruction on how to build and run t
 For building:
 
 - Docker. Any recent version with support for multi-stage builds should work, e.g. Docker Engine 20.x.
-- Singularity. Targeted version 3.5.3. (Not required for building on personal machine.)
+- Singularity. Targeted version 3.5.3. (Not required if building ONLY for use with Docker on personal machine.) Please also see the "Installing Singularity" section.
+- At least 20GB free disk space.
 
 For running on Garrawarla:
 
@@ -53,34 +54,38 @@ For integration testing:
 - Pytest. Targeted version 4.6.9.
 - `mwatdr_utils`. Please see `mwatdr_utils/README.md` for its requirements.
 
+Note: "targeted version" means the version the software is guaranteed to work with.
+Similar versions that aren't significantly older or newer may also work.
+
 ## Building and Running `main` for Use on Garrawarla
 
 The instructions here are for building and running the main application for use on Garrawarla - if you are a standard user, this is probably what you want to do.
 
 ### Building
 
-First, build the `main` target with Docker on your personal machine (since Garrawarla does not have Docker), using the provided script:
+First, we will build the `main` target with Docker on your personal machine, since Garrawarla does not have Docker.
+
+Note that you must perform the following step on an x86 machine, to match the CPU architecture of Garrawarla.  
+(By default, Docker build will use base images which match the current system architecture.
+If you wish to build on other types of systems, you can modify the Dockerfile to explicitly specify the architecture.)
+
+Run the provided build script as follows:
 
 ```bash
 ./docker_build.sh main Release garrawarla singularity
 ```
 
-This invokes Docker to build the main application image, using a configuration optimised for high performance on Garrawarla, and designed to run with Singularity.
-The name of the image is `mwatdr/main`.  
-Note that you must perform this step on an x86 machine, to match the CPU architecture of Garrawarla.
-By default, Docker build will use base images which match the current system architecture.
-You can modify the Dockerfile to manually specify the architecture if you wish to build on other types of systems.
-
-The build will probably take quite a while the first time, due to some large libraries which are installed and built in the image.
-Do not be alarmed if it takes over 20 minutes.
+This invokes Docker to build the main application image, using a configuration optimised for high performance on Garrawarla, and designed to run with Singularity. It will probably take quite a while the first time, due to some large libraries which are installed and built in the image.  
+The resulting image is named `mwatdr/main` and is approximately 5.5GB in size.  
+At this stage, the image is stored internally within Docker - no visible file output is produced.
 
 Next, you need to convert the Docker image to a Singularity image.  
 There are a few options for which system to perform the conversion on:
 
-- Use Singularity installed on your personal machine. Installation of Singularity is easy if you use Linux or Mac, but difficult for Windows.
-- Use Singularity already installed on Garrawarla, either on the login nodes or on the compute nodes with an interactive SLURM job. Using the compute nodes is likely fastest to build, but it does require transferring the >5GB Docker image to Garrawarla first.
+- Use Singularity installed on your personal machine. The difficulty of installation depends on your operating system. Please see the "Installing Singularity" section for details.
+- Use Singularity already installed on Garrawarla, either on the login nodes or on the compute nodes with an interactive SLURM job. However, it does require transferring the >5GB Docker image to Garrawarla first. This is our recommended method if you have a good internet connection.
 
-Convert the Docker image to tar format:
+Convert the Docker image to a tar file:
 
 ```bash
 docker save mwatdr/main -o main.tar
@@ -97,7 +102,8 @@ This takes the `main.tar` Docker image you just saved and produces `main.sif`, t
 By default, Singularity uses the system temporary directory for working space, and may use a few gigabytes of space, which may be an issue for some systems - particularly Linux, where `/tmp` may be in RAM.  
 Therefore it is highly recommended to set `<some_dir>` to somewhere on disk.
 
-The Singularity build may take several minutes to complete.
+The Singularity build may take several minutes to complete.  
+The resulting image will be approximately 1.5GB in size.
 
 ### Running
 
@@ -115,13 +121,13 @@ sbatch slurm_main.sh <args>
 
 ## Building and Running `main` for Use on Personal Machine
 
+The instructions here are for building and running the main application for use on your personal, standard computer.
+This may be useful for testing purposes.
+
 NOTE: The application is designed to run on Garrawarla, and your personal machine may not be powerful enough to feasibly run the `main` target.  
 For 24 frequency channels and 256 antenna inputs, we found `main` requires approximately 8GB of memory per process, and running with a few processes will take on the order of a few hours to complete.  
 It is possible to manually specify the number of processes to `mpirun` in `entrypoint.sh`, but there will be a tradeoff between memory usage and run time.
 
-The instructions here are for building and running the main application for use on your personal, standard computer.
-This may be useful for testing purposes.
-
 First, build the `main` target with Docker, using the provided script:
 
 ```bash
@@ -138,6 +144,27 @@ Then simply run the `main` target with Docker, using the provided script:
 
 `<args>` are the application command line arguments. Please see the "User Interface" section for details.
 
+## Installing Singularity
+
+If you are building the application to run on Garrawarla, you will need to have Singularity installed on whichever machine you use to perform the build.  
+If you choose not to build on Garrawarla, you will need to install Singularity yourself.
+
+### Linux
+
+Depending on your distro, prebuilt Singularity packages may be available for simple installation from your package manager. Try searching for "singularity" or "singularity-container".
+
+Alternatively, you may need to build from source. Instructions can be found [here](https://sylabs.io/guides/3.8/admin-guide/installation.html#installation-on-linux) from Singularity and [here](https://pawseysc.github.io/singularity-containers/44-setup-singularity/index.html) from Pawsey.  
+
+### Mac
+
+Installation on Mac may be done by building Singularity from source, or using a Vagrant virtual machine.
+Instructions can be found [here](https://sylabs.io/guides/3.8/admin-guide/installation.html#installation-on-windows-or-mac).
+
+### Windows
+
+Installation on Windows may be done by building Singularity from source, or using a Vagrant virtual machine.
+Instructions can be found [here](https://sylabs.io/guides/3.8/admin-guide/installation.html#installation-on-windows-or-mac).
+
 ## User Interface
 
 The `main` target has the following positional command line arguments:

src/Main.cpp

@@ -180,7 +180,7 @@ void runNode(PrimaryNodeCommunicator& primary, int argc, char* argv[]) {
         std::cerr << "Node 0 (Primary): " << e.what() << std::endl;
     }
 
-    std::cout << "Node 0 (Primary): Terminated succesfully" << std::endl;
+    std::cout << "Node 0 (Primary): Terminated successfully" << std::endl;
 }
 
 

src/OutputLogFileWriter.cpp

@@ -59,6 +59,7 @@ void writeProcessingDetails(std::ofstream& log, ChannelRemapping const& channelR
 	double samplingPeriod = (1.0 / sampleRate) * 1000.0;
 
     log << "SIGNAL PROCESSING DETAILS" << std::endl;
+    log << "Integer length of Fourier transform: " << channelRemapping.newSamplingFreq << std::endl;
     log << "Output sample rate: " << roundThreeDecimalPlace(sampleRate) << " MHz" << std::endl;
     log << "Output sampling period: " << roundThreeDecimalPlace(samplingPeriod) << " ns\n" << std::endl;
 }