Squishy Electron
================

This project is at alpha quality.  (I like doing it all myself.)


Requirements for Running
========================

The most important factor is your browser, and what features it supports.  I've given years rather than version numbers; most modern mainstream browsers should support all of these if they are reasonably up to date

Browser availability: most up-to-date browswers should run Squishy Electron fine.  Older browsers:
- Chrome dated 2017 or later
- Firefox dated 2017 or later
- Safari (both) dated 2020-21 or later
- Edge dated 2020-21 or later
- Android browsers dated 2016-2020, depending on your browser

Versions
========

v3 refers to the previous SquishyElectron project. (obsolete)
v4 is squishy_electron_4, this project, v0.4 and later.

Files
=====

The top level of the source is a standard React project from CreateReactApp.

src - the main JS sources
src/App.* - top level JS
src/controlPanel - all the stuff south of the main display
src/engine - interface to the C++
src/gl - WebGL code
src/sPanel - main SquishPanel code
src/utils - misc non-html functions
src/view - main display, uses gl
src/widgets - misc React components used in multiple places

public - misc files that the web app needs to be served, like index.html
    These files will  be copied into the runnable site; symlinks followed.
public/fonts/ - math fonts for docs
public/index.html, manifest.json, robots.txt - the usual
public/images/ - pngs etc used in app
public/logos/ - svgs and pngs that are logos, incl favicon
public/qEng/ - symlinks to the quantum engine compiled objects

LICENSE, node_modules/, package-lock.json, package.json - the usual
Makefile - mostly runs stuff in quantumEngine
README.react.md - original README.md generated by CRA
articles/ - my research & notes for this project
build/ - where a production build goes
maint/ - scripts I need here and there that CRA has no place for; mostly building production

quantumEngine - the C++ code that does the numerical calculations
quantumEngine/Makefile - how to compile it all
quantumEngine/building/ - scripts to compile it all
quantumEngine/commonConstants.h - generated
quantumEngine/debroglie/ - wave buffers
quantumEngine/directAccessors.h - a way for JS to access C++ object fields directly
quantumEngine/fourier/ - FFT code
quantumEngine/greiman/ - Avatar, view buffer and other visual stuff
quantumEngine/hilbert/ - mostly the qSpace
quantumEngine/main.cpp - main C++ function, runs when C++ starts up
quantumEngine/schrodinger/ - code that actually integrates Schrodinger's equation
quantumEngine/squish.h - global include file
quantumEngine/testing/ - scripts etc specifically for testing C++ code
quantumEngine/wasm/ - compiled WASM & JS output both dev and prod


Scripts
=======

To run scripts this project, you need to export SQUISH_ROOT to point to the
source directory in one of your login files like this:

export SQUISH_ROOT='/opt/dvl/squishyElectron/SquishyElectron'

For testing the C++, you need to install CppUTest, and put this also in your profile:

export CPPUTEST_HOME=/opt/dvl/cpputest/cpputest-3.8

Usually the file ~/.profile works; if you already have another file with
a name like ~/.*profile*, that would probably be better.  Otherwise,
create .profile .

If you're using BASH, you might also like to put this in your ~/.bashrc
file, or if you have an existing ~/.*rc file for your shell:

source $SQUISH_ROOT/maint/aliases.sh

it'll define some aliases to quickly zip around among the important directories in the terminal.

## quantumEngine

This is C++ code that runs directly in the browser.  It relies on
[WebAssembly](https://developer.mozilla.org/en-US/docs/WebAssembly/Concepts)

On top of that, the
[Emscripten] package compiles and links C++ to make
.wasm and other object files.  So, if you want to build this, you have
to install it.

https://emscripten.org

Export qEMSCRIPTEN to point to the directory in one of your login files like .profile :

export qEMSCRIPTEN=/opt/dvl/emscripten

The scripts will be expecting it.

## internal operation


- a 'Space' describes where the electron travels.  (Classes qSpace in
C++ or eSpace in JS.)  Most important parts:
- N = number of datapoints in
	a wave, always a power of two, typically 32 thru 512
- continuum = int enum that describes the edges of the space: wall or endless These two
values dictate the wave buffers allocated all over.  If the user changes
either, everything is tossed and reallocated.

- a 'Wave' is an array of N psi  values, each a complex number (two doubles, class qCx).  There's actually several classes:
	- qWave and eWave is a quantum system state; wrapped array of complex nums
	- qSpectrum is an FFT of a qWave; wrapped array of complex nums
	- qBuffer is the superclass of the qWave and qSpectrum
	- qWaves usually have an extra point on each end to aid in calculations, so if N=32, there's 66 double floats in the buffer.  Methods named fixBoundaries() automatically implement the details.

- an 'Avatar' manages display of a Wave.  There's two per space; the second one is for the Set Wave minigraph.  It owns a qViewBuffer, which is ultimately handed to WebGL.  (to be merged into avatar)

- a 'Grinder' integrates the differential equation.


## emscripten

[Get Started with Emscripten](https://emscripten.org/docs/getting_started/downloads.html)

then from the top level run this (or, make will do it):

quantumEngine/building/genExports.js

Go change that file as you add more C++ exports you want to call from
JS.  They all have to be "C" functions, see the code.  Note there's a
fair amount of overhead for each call; trace it in the debugger to see.
This is why I made the DirectAccess system; see directAccess.h, and
classes that use it: e/qWave, e/qGrinder, Avatar


-------------------- node and python

I had to upgrade my Python to 3.9.5, otherwise the 'install' wouldn't work.  And then, add the 'certificates'.

It has its own version of Python (3.9 or so), and also its own version of node (v16 or beyond).
It'll use its own versions so don't worry about any version(s) you already have installed.

oh yeah, here:
emsdk uninstall node-14.15.5-64bit
emsdk uninstall python-3.9.2-1-64bit

get the installed version numbers:
./emsdk list

----------------------

this is automatically done in the build scripts so you don't have to put them into your .profile or whatever files:

. /dvl/emscripten/emsdk/emsdk_env.sh

## serving

These two headers must be sent with (some or) all of the files from the server:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

If not, the thread stuff can't start up, the page can't start up, and it
all goes down the tubes.  (until you fix it, that is.)  :
[See also](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src)

for nginx:
```
	add_header Cross-Origin-Opener-Policy same-origin;
	add_header Cross-Origin-Embedder-Policy require-corp;
```