scuff em and Windows operating system - HomerReid/scuff-em GitHub Wiki

Introduction

I've just got scuff-em running on a Windows 10 laptop. It's straightforward. But it took me a while because I didn't know what to do. So I thought I should share my experience in case it's helpful for other novices.

I didn't build scuff-em from the source code (which might be an option for experts). Instead I used the Docker option. This might have the disadvantage that it might not run as fast as scuff-em built from source code on your computer (although I don't know this for sure). It is fast enough for my needs, so here is my guide to getting scuff-em running using Docker and Windows.

Step 1: Your computer needs to be able to run Docker

To find out if your computer can run Docker I guess you can either check the system requirements or just try downloading and installing Docker Desktop for Windows and seeing what happens (for Version 3.1 of the Docker Desktop Installer the download is about 500MB and you only need to do it once).

Assuming you decide to download and install, upon completion of the process (which I think includes restarting your computer), if you open a Command Prompt and type docker --help you should get a list of Docker options and commands. I've managed to use scuff-em without any knowledge of these options and commands --- I mention the list only because, if you can't produce it, something is definitely wrong (and perhaps the options and commands might be helpful to others). Further information about Docker is available if you want it.

As already alluded to, you only need to download and install Docker once --- you can then use it as often and whenever you like.

Step 2: Pull the Docker image

With Docker installed, type at the Command Prompt (you still need internet access for this step): docker pull jfeist/scuff-em This will download the Docker image of scuff-em onto your computer. The download is about 700MB but, as with Docker, you only need to do it once. The process should produce some output at the Command Prompt, ending with: Status: Downloaded newer image for jfeist/scuff-em:latest If everything has worked correctly, you can now use scuff-em as often and whenever you like and no internet connection is required.

Step 3: Download the scuff-em files

This isn't necessary to use scuff-em (because the Docker image has everything needed). But it is helpful if you want to run the tutorial examples (Step 4 below). And it's not a huge download (about 38MB). Download the .zip file (it's a link off the scuff-em GitHub page). Unzipping it should make a folder scuff-em-master which contains all the subfolders and files of scuff-em.

Step 4: Try one of the tutorial examples

Because my main interest is scattering problems, I chose the Mie Scattering example.

Using File Explorer (or otherwise) create a folder which scuff-em will use as its working directory for the tutorial example (scuff-em will look for input files in this folder and write output files to this folder). I created a folder named MyAttemptAtMie in my root directory C:\Users\Wardle.

The input files needed for the Mie Scattering example are in the folders scuff-em-master\doc\docs\examples\MieScattering and scuff-em-master\examples\SolidSphere. Following the Mie Scattering documentation, copy the needed files from these folders to the MyAttemptAtMie folder (I emphasize 'copy' rather than 'move' --- you probably want to avoid changing scuff-em-master and its contents). It's also worth opening the files with e.g. Notepad and confirming their contents are as described in the Mie Scattering documentation. If you wish to play with gmsh there's a Windows version (it's about 31MB to download and, once downloaded and unzipped, it has an easy-to-use, non-internet dependent, graphical user interface, accessible by double-clicking on the file gmsh.exe).

Change the working directory at the Command Prompt to the folder MyAttemptAtMie. I do this by typing at the Command Prompt: cd "C:\Users\Wardle\MyAttemptAtMie"

To run the Mie scattering example, I now simply type at the Command Prompt: docker run -i -v "C:\Users\Wardle\MyAttemptAtMie":/mnt jfeist/scuff-em scatter < Args

This takes about ten minutes to run on my laptop and writes a file SiCSphere.PFT in the folder MyAttemptAtMie. Using the data in SiCSphere.PFT I can produce my own version of: scuff-em-master\doc\docs\examples\MieScattering\SiCData.png I find my version matches SiCData.png except for the points that are for absorbed power for sphere size parameters greater than 1. I think this mismatch might be OK and not indicative of a problem with scuff-em running on my computer. My reasoning is that, for the mismatching points, round-off errors (or other numerical artefacts) might be dominating the results. Evidence for this is that:

The points don't match the Mie theory predictions.
I have found that small changes to the meshing of the sphere significantly changes the position of the points.

Round-off errors will depend on the architecture of the computer and hence the position of the points might differ from computer to computer even if the computers are faithfully running exactly the same code. Do others (especially those running scuff-em built from source code rather than running under Docker) observe a similar mismatch? It would be reassuring if they did...

Preparing files

One thing to note. Open one of the tutorial files e.g. scuff-em-master\examples\SolidSphere\SiCSphere.scuffgeo with Notepad. Along the bottom of the Notepad window there is the Status Bar (if it's not present, make it visible from the View drop-down menu). It will read (among other things) Unix (LF). Although .msh files appear to be an exception, some of the other files for input to scuff-em need to be in this format. If you make a .txt file (using Notepad or otherwise) on a Windows computer, the file will not be in this format (it will be Windows (CRLF)). So, when you want to make your own files to input to scuff-em, do it by making a copy of e.g. SiCSphere.scuffgeo, edit the contents of the copy to suit your purposes, and then save it under the filename of your choosing. That way your file will have the appropriate (Unix (LF)) format.

Versions and bugs

Following these instructions (particularly Step 2), you will be running (at the time of writing) an April 2020 version of scuff-em. This might have some bugs in it. You can, if you wish, revert to an older version (although this might just mean you have different bugs...).