Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding Ember documentation #1948

Open
wants to merge 767 commits into
base: devel
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
767 commits
Select commit Hold shift + click to select a range
8fabb86
fix bug in AMOADD
mjleven Mar 2, 2023
d6b8699
use exe env0 to set OMP_NUM_THREADS
mjleven Mar 2, 2023
34ca103
add openmp test
mjleven Mar 2, 2023
f23777f
update gold file
mjleven Mar 3, 2023
6e4e7fd
OSX has different errno values, use LINUX errno values
mjleven Mar 3, 2023
f3f088a
fix futex so waiters are ordered on different operating systems
mjleven Mar 3, 2023
f1e4ce5
fix futex so it orders waiters
mjleven Mar 3, 2023
84a8be6
update gold files
mjleven Mar 3, 2023
845df12
fix order of processes in group because old way results in different …
mjleven Mar 3, 2023
9bb7b18
Clean up code for better readability.
frothga Jul 7, 2022
94fe279
Move to Fugu neuron model
frothga Jul 7, 2022
d16b56b
Read network from input file
frothga Aug 16, 2022
c18300a
More efficient model file format
frothga Aug 18, 2022
4ad06f8
Remove old-style inputs
frothga Aug 18, 2022
466e4c9
Use Neuron pointer rather than index to track spikes
frothga Aug 18, 2022
0f904e6
Example Fugu app now runs correctly
frothga Aug 19, 2022
1d97cd5
Default column names to handle probes besides 'spike'
frothga Aug 25, 2022
4a95d0b
GNA: update testsuite
frothga Feb 27, 2023
f94260b
GNA: fix some missing files in make configuration
frothga Feb 28, 2023
f8ed368
GNA: remove dependency of test on Python package re
frothga Feb 28, 2023
f4fa4b3
GNA: remove dependency of test on Python package numpy
frothga Feb 28, 2023
f5fc5be
GNA: Fix type error
frothga Feb 28, 2023
1becd7c
GNA: initialize V properly
frothga Mar 2, 2023
55bf223
Minor fixes for compile warnings, ember typo, update config output
gvoskuilen Mar 2, 2023
b001f74
Initial version of support for dragonfly topology with more than one …
feldergast Mar 3, 2023
c04e92c
Short circuit loads at address zero in the LSQ by marking potential e…
Feb 24, 2023
2ccd3e1
Update for short cycle loads at address zero in the LSQ.
Mar 5, 2023
f87f5de
Use templates to remove branches from code generation.
Mar 6, 2023
f055cd3
Reorder parameters to try to increase some locality in access.
Mar 6, 2023
f23e641
Small tweaks.
Mar 6, 2023
14a58c1
Switch shift immediate over to standard types to decrease branching.
Mar 6, 2023
2a7565a
Switch set-branch-compare over to basic types.
Mar 6, 2023
c17aa14
Updated merlin python so you can get a handle to the loaded module fr…
feldergast Mar 8, 2023
0eececc
not getting the AQ and RL bits correctly
mjleven Mar 8, 2023
be7480f
fix gold files after change to riscv decoder to fix bug
mjleven Mar 8, 2023
37de887
MemH: Add ability to stall LL conflicts for some amount of time
gvoskuilen Mar 7, 2023
5977800
MemH: Fix FetchInvX handling for locked line
gvoskuilen Mar 8, 2023
d58ee23
Fix FetchInvX cleanup
gvoskuilen Mar 8, 2023
baccb15
Eliminate sprintf deprecation warnings
gvoskuilen Mar 9, 2023
b460197
Ariel: Fix snprintf
gvoskuilen Mar 13, 2023
1018ee4
kill child process in finish phase if it is still running
plavin Mar 13, 2023
21b5a29
update
mjleven Mar 13, 2023
7cbfaa2
update openmp executable
mjleven Mar 13, 2023
ee0d29a
update gold files because of futex fix
mjleven Mar 13, 2023
7a879ca
support multiple debug addresses
mjleven Mar 13, 2023
b9b4c84
fix FUTEX so it read the WAIT value atomicaly
mjleven Mar 13, 2023
19f139c
update debug
mjleven Mar 14, 2023
d4dafab
add core ID to LSQ so we can print it in debug output
mjleven Mar 14, 2023
4828eaa
git hardware threads working and updte debug printout
mjleven Mar 16, 2023
ad930da
fix retire
mjleven Mar 16, 2023
2580221
fix mistaken commit
mjleven Mar 16, 2023
231ca37
update gold files for hardware threads
mjleven Mar 16, 2023
1535287
add new gold files
mjleven Mar 16, 2023
eef6725
support multiple tests for the same vanadis exe
mjleven Mar 16, 2023
d788168
fix typo
mjleven Mar 16, 2023
495887a
New way to ingest graphs (csv)
hughes-c Mar 23, 2023
95334ce
Update PE types including streams
hughes-c Mar 23, 2023
37d8ea0
Cleaning. All the moo cows.
hughes-c Mar 23, 2023
4f089b9
Fixed PE latency -- can now set latency using config params
hughes-c Mar 24, 2023
d74041a
Fixed FP description so that it makes more sense.
hughes-c Mar 24, 2023
b2e599b
Switch to basic types to improve code generation.
Mar 11, 2023
956a4fc
fix bug, need to set OMP num threads to numCores * numThreds
mjleven Mar 21, 2023
cf02441
update gold files after fix of basic_vanadis.py
mjleven Mar 21, 2023
79148ed
add 2 thread 2 core openmp test
mjleven Mar 21, 2023
846970c
moved some gold files to more descriptive directory names and add new…
mjleven Mar 21, 2023
05779df
update gold files
mjleven Mar 21, 2023
33cacd9
scale Vanadis CPU physical registers by number of hardware threads
mjleven Mar 21, 2023
eff0535
fix gold file directory name
mjleven Mar 21, 2023
c7adaba
move reset of pending count to seperate function
mjleven Mar 21, 2023
74f57d7
remove clear() and make reset() private
mjleven Mar 21, 2023
5505d3e
- add new member function that returns unused out registers to the ph…
mjleven Mar 21, 2023
da84e87
change from physical register stack per hardware thread to 1 physical…
mjleven Mar 21, 2023
6edbb59
make debug output consistent
mjleven Mar 21, 2023
c61f403
fix file names
mjleven Mar 21, 2023
03ea6e6
Missing update from branch to fix compile error.
Mar 21, 2023
06a85f7
add new syscalls: fstatat, getrandom, prlimit, readlinkat, setrobustlist
mjleven Mar 23, 2023
6eedd29
fix OSX typo
mjleven Mar 23, 2023
459c5f4
fix mprotect, it was not spliting a region properly
mjleven Mar 23, 2023
ce01c8f
add name
mjleven Mar 23, 2023
501fc89
cleanup debug
mjleven Mar 24, 2023
f7b34c3
code cleanup
mjleven Mar 24, 2023
644621e
MH: Fix missing symbol in goblin hmcsim; remove dmaEngine from ELI
gvoskuilen Mar 27, 2023
fce6033
fix error for OSX
mjleven Mar 24, 2023
06fa5ea
move toward unified os handler for both MIPS and RISCV with some temp…
mjleven Mar 28, 2023
1945eb0
fix name of variable for ifdef OSX
mjleven Mar 28, 2023
9643405
fix gold files adter removing declocking code
mjleven Mar 28, 2023
b4724d4
remove code that de-clocks the CPU
mjleven Mar 28, 2023
a9446e4
update gold file
mjleven Mar 28, 2023
3b98e7b
add pin-3.26 compatibility, remove pin2 references
plavin Mar 29, 2023
fa8f0f2
fix syscall name
mjleven Mar 30, 2023
93c22bd
add some syscalls
mjleven Mar 30, 2023
e39edc6
remove used event
mjleven Mar 30, 2023
dd6a209
clean up the OS handler with common code where possible
mjleven Mar 30, 2023
0ce67d9
a bit more cleanup
mjleven Mar 30, 2023
fb0f985
update gold files
mjleven Mar 30, 2023
ecbecc0
remove deleted file
mjleven Mar 30, 2023
489b15e
fix AT_FDCWD
mjleven Mar 31, 2023
1e31dd2
Changed stopAtCycle to stop-at in input python files because stopAtCy…
feldergast Mar 31, 2023
0a63011
Updated CramSim, Opal and Samba to remove use of deprecated (or soon …
feldergast Apr 6, 2023
7afb4b3
Update VaultSimC, ariel, cacheTracer, cassini, prospero, shogun and t…
feldergast Apr 6, 2023
cecb3e0
Introduce custom cuda lib
William-An Mar 1, 2022
b6d1070
Add init mmio class for balar
William-An Mar 17, 2022
4b65313
Copy from original balar
William-An Mar 17, 2022
2c8eac4
Create test mmio device for balar
William-An Mar 18, 2022
13b32c9
Update makeflie and devnote
William-An Mar 18, 2022
a31c38f
Balar: add test cpu
William-An Mar 19, 2022
5b7e120
balar: move testcpu to balarComponent
William-An Mar 22, 2022
ad8e84f
balar: add test cpu launch script
William-An Mar 22, 2022
5f2f7e5
Add module gitignore
William-An Mar 22, 2022
160ce22
balar: create cuda call packet and test with testcpu
William-An Mar 22, 2022
22f43c8
balar: create handlers in testcpu to receive response from balarMMIO
William-An Mar 23, 2022
c2f4989
balar: call gpgpusim on packets
William-An Apr 8, 2022
4b665af
balar: use template methods to handle call and return packets
William-An Apr 8, 2022
3f7633a
Add a trace parser to drive the test cpu
William-An May 12, 2022
1bcedb4
balar: Add memcpy data loading to parser
William-An May 12, 2022
e2ec34b
balar: add kernel launch support for parser
William-An May 12, 2022
f86ce87
balar: compare device copy results with actual data, need to wait for…
William-An May 13, 2022
aaabb14
balar: add callback funcs to let gpgpusim notify sst a blokcing api i…
William-An May 13, 2022
c65e081
balar: stage for preparation to add gpu cache to balar
William-An May 18, 2022
66b377b
balar: copy original script for gpu cache config
William-An May 18, 2022
250adc6
balar: fixed performance simulation by adding memory ssubsystem
William-An May 19, 2022
b14269c
Update notes
William-An May 19, 2022
2ad9541
balar: disable debug traces for gpgpusim
William-An May 19, 2022
b58ec3a
balar: rm unneeded files and prepare for stats analysis
William-An May 20, 2022
853ad97
balar: add few debug options to original balar config file
William-An May 31, 2022
47d3671
balar: balarTestCPU pad the kernel argument to ensure alignment
William-An May 31, 2022
3f74402
balar: Add testvanadis file
William-An Jun 2, 2022
2a87b6c
Add vanadis config file to balar
William-An Jun 2, 2022
d699cbb
balar: add modified vanadis and balar config script
William-An Jun 2, 2022
010c9f6
balar: restore previous commit
William-An Jun 2, 2022
4086bfd
balar: add statistics to testcpu on memcpy and add option to dump mem…
William-An Jun 6, 2022
c816124
balar: update devnote and comment out conflicting makefile settings
William-An Aug 11, 2022
8f5fd4b
balar: try to test vanadis handshake binary with latest sst (12.x)
William-An Aug 11, 2022
287f1ec
balar-mmio: modify balarMMIO to load packet from passed in address an…
William-An Sep 6, 2022
80ca4ba
balar-mmio: finish modifying balarmmio to pass packets via pointer
William-An Sep 7, 2022
79921c9
balar-mmio: finish porting the testcpu to the new cuda call interface
William-An Sep 22, 2022
6dbcdd0
balar-mmio: clean up unused code in BalarTestCPU
William-An Sep 23, 2022
8ac9e0b
balar-mmio: add comment and remove unused code in BalarMMIO
William-An Sep 23, 2022
ad756cf
balar-mmio: remove legacy code
William-An Sep 28, 2022
3505639
balar-mmio: update test binary
William-An Sep 28, 2022
753f9f3
balar-mmio: update balarMMIO to read pointer value from sst memory space
William-An Sep 28, 2022
e8ea6c1
balar: add dmaEngine to copy data from sst mem space to simulator mem…
William-An Oct 20, 2022
c4093ea
balar: use dma engine to handle memcpy data transfer
William-An Oct 20, 2022
5a78417
balar: fix some bugs that prevent using balar with DMA
William-An Oct 20, 2022
1573549
balar: fix a bug in balarMMIO that cause memcpy data to be incorrect …
William-An Oct 21, 2022
e066bf4
balar: fix DMA engine to report done correctly at the last transfer
William-An Oct 21, 2022
b40c78b
balar: able to launch vectorAdd from vanadis program
William-An Oct 23, 2022
6ae4238
balar-mmio: fix minor typo
William-An Nov 11, 2022
06aa5cf
balar: add synchronization support to balar for cudaMemcpy
William-An Dec 2, 2022
542c982
balar-mmio: modify configuration scripts and vanadis binary to adapt …
William-An Jan 7, 2023
0f6f514
balar-mmio: fix cudalaunch stream issue by initializing stream to NUL…
William-An Jan 13, 2023
9f7e827
balar-mmio: organize test scripts and update readme
William-An Feb 13, 2023
7bc95f4
balar-mmio: update xbar configuration in testcpu run script
William-An Feb 15, 2023
cd3d396
balar-mmio: update testvanadis run script to match with newest
William-An Feb 15, 2023
797ead1
Update balar readme
William-An Mar 19, 2023
ab17c2a
balar-mmio: Update testsuite files for balar
William-An Mar 21, 2023
9d34fcc
Introduce custom cuda lib
William-An Mar 1, 2022
534ccf9
Add init mmio class for balar
William-An Mar 17, 2022
9f5d82a
Copy from original balar
William-An Mar 17, 2022
c7e299b
Create test mmio device for balar
William-An Mar 18, 2022
7e431e7
Update makeflie and devnote
William-An Mar 18, 2022
751dfec
Balar: add test cpu
William-An Mar 19, 2022
7e999e4
balar: move testcpu to balarComponent
William-An Mar 22, 2022
dbc174b
balar: add test cpu launch script
William-An Mar 22, 2022
3149de5
Add module gitignore
William-An Mar 22, 2022
9a2fa51
balar: create cuda call packet and test with testcpu
William-An Mar 22, 2022
f087490
balar: create handlers in testcpu to receive response from balarMMIO
William-An Mar 23, 2022
24b9377
balar: call gpgpusim on packets
William-An Apr 8, 2022
2a9cadd
balar: use template methods to handle call and return packets
William-An Apr 8, 2022
77b27b5
Add a trace parser to drive the test cpu
William-An May 12, 2022
918f56c
balar: Add memcpy data loading to parser
William-An May 12, 2022
cb43108
balar: add kernel launch support for parser
William-An May 12, 2022
8b060f5
balar: compare device copy results with actual data, need to wait for…
William-An May 13, 2022
263d2b1
balar: add callback funcs to let gpgpusim notify sst a blokcing api i…
William-An May 13, 2022
91c8f17
balar: stage for preparation to add gpu cache to balar
William-An May 18, 2022
7e2e1dd
balar: copy original script for gpu cache config
William-An May 18, 2022
0f1cc1d
balar: fixed performance simulation by adding memory ssubsystem
William-An May 19, 2022
8ff43c5
Update notes
William-An May 19, 2022
b653db0
balar: disable debug traces for gpgpusim
William-An May 19, 2022
a755691
balar: rm unneeded files and prepare for stats analysis
William-An May 20, 2022
e52a979
balar: add few debug options to original balar config file
William-An May 31, 2022
2c8628c
balar: Add testvanadis file
William-An Jun 2, 2022
703f21e
Add vanadis config file to balar
William-An Jun 2, 2022
ff01bc3
balar: update vanadis handshake
William-An Jun 2, 2022
8fa2cc9
balar: add modified vanadis and balar config script
William-An Jun 2, 2022
f845a83
balar: restore previous commit
William-An Jun 2, 2022
6e2587b
balar: add statistics to testcpu on memcpy and add option to dump mem…
William-An Jun 6, 2022
d652e9c
balar: update devnote and comment out conflicting makefile settings
William-An Aug 11, 2022
7fb0739
balar: try to test vanadis handshake binary with latest sst (12.x)
William-An Aug 11, 2022
217035b
balar-mmio: modify balarMMIO to load packet from passed in address an…
William-An Sep 6, 2022
db65cd3
balar-mmio: finish modifying balarmmio to pass packets via pointer
William-An Sep 7, 2022
737ce51
balar-mmio: finish porting the testcpu to the new cuda call interface
William-An Sep 22, 2022
70400f0
balar-mmio: clean up unused code in BalarTestCPU
William-An Sep 23, 2022
13d34d0
balar-mmio: remove legacy code
William-An Sep 28, 2022
f44b5b4
balar-mmio: update test binary
William-An Sep 28, 2022
8d82d58
balar-mmio: update balarMMIO to read pointer value from sst memory space
William-An Sep 28, 2022
6e96676
balar: add dmaEngine to copy data from sst mem space to simulator mem…
William-An Oct 20, 2022
4435512
balar: use dma engine to handle memcpy data transfer
William-An Oct 20, 2022
d31b1d9
balar: fix some bugs that prevent using balar with DMA
William-An Oct 20, 2022
8b91ac2
balar: fix a bug in balarMMIO that cause memcpy data to be incorrect …
William-An Oct 21, 2022
34cf82b
balar: fix DMA engine to report done correctly at the last transfer
William-An Oct 21, 2022
32bbe98
balar: able to launch vectorAdd from vanadis program
William-An Oct 23, 2022
8606d21
balar-mmio: fix minor typo
William-An Nov 11, 2022
1dea68a
balar: add synchronization support to balar for cudaMemcpy
William-An Dec 2, 2022
7bf9641
balar-mmio: modify configuration scripts and vanadis binary to adapt …
William-An Jan 7, 2023
802157d
balar-mmio: fix cudalaunch stream issue by initializing stream to NUL…
William-An Jan 13, 2023
9725205
balar-mmio: organize test scripts and update readme
William-An Feb 13, 2023
ac94f19
balar-mmio: update xbar configuration in testcpu run script
William-An Feb 15, 2023
2dfaf24
balar-mmio: update testvanadis run script to match with newest
William-An Feb 15, 2023
79a303f
Update balar readme
William-An Mar 19, 2023
d79d819
balar-mmio: Update testsuite files for balar
William-An Mar 21, 2023
8246567
balar: restore testStdMem-mmio.py
William-An Mar 24, 2023
61423ec
balar: removed unused commented features and update devnote
William-An Mar 24, 2023
1ea9b07
balar: format test scripts
William-An Mar 24, 2023
be47a56
Update Makefile.am
hughes-c Mar 23, 2023
f456127
balar: restore splitload from vanadis
William-An Mar 24, 2023
992cf74
balar: removed some comments from vanadis handshake test files and ad…
William-An Mar 24, 2023
7a3f4ec
balar: update Makefile.am to include test files for distribution
William-An Mar 24, 2023
7733f51
balar: remove old balar code
William-An Mar 30, 2023
2bc85f5
balar: remove old balar and ariel related configs from test scripts
William-An Mar 30, 2023
3b6fb93
balar: update reference file
William-An Mar 30, 2023
2e70563
balar: add new config file
William-An Mar 30, 2023
f61733a
balar: fix Makefile.am as config file gets renamed
William-An Apr 4, 2023
5bd8076
Added int mul latency.
Apr 10, 2023
060cae9
split vcpuos.h into two files so the base class is seperate
mjleven Apr 10, 2023
c792eee
fix compiler warnings
mjleven Apr 11, 2023
861b0dd
fix compiler warnings
mjleven Apr 11, 2023
0babc39
fix compiler warnings
mjleven Apr 11, 2023
37af827
fix compiler warnings
mjleven Apr 11, 2023
d0df930
fix compiler warnings
mjleven Apr 11, 2023
d0dbc32
Remove deprecation warnings for GNA, miranda, mmu, osseous and serrano.
feldergast Apr 11, 2023
5a6f7ad
cleanup up compiler warnings
mjleven Apr 11, 2023
49ee78d
Remove deprecated functions from merlin.
feldergast Apr 12, 2023
a4a176c
Updated memH to remove use of deprecated functions.
feldergast Apr 12, 2023
d953868
Removed use of deprecated functions from ariel, ember, firefly, kings…
feldergast Apr 12, 2023
ac903f9
Copyright date update: CramSim-kingsley
gvoskuilen Apr 13, 2023
210a01c
Update copyrights: CramSim, llyr-zodiac
gvoskuilen Apr 14, 2023
8452567
fix compiler warnings and a bug
mjleven Apr 19, 2023
50b4400
remove bug fix for now
mjleven Apr 19, 2023
017e873
fix check of page perms
mjleven Apr 19, 2023
f9eff6a
update gold files after fix to mmu
mjleven Apr 20, 2023
9eb91d8
fix TLB when a wait miss has perms that don't match
mjleven Apr 20, 2023
e801d3c
remove various elements including:
jmlapre Apr 21, 2023
3f9a774
bump version to 13.0.0
jmlapre Apr 21, 2023
6ec6a35
bumped copyright to 2023 in ember/run/configuratioins
jmlapre Apr 21, 2023
4f70bad
remove osseous
jmlapre Apr 21, 2023
6d026fd
Revert "V13.0.0 beta"
jmlapre Apr 24, 2023
c81a227
rebase with devel
nab880 Oct 30, 2024
4ce6d7e
Merge branch 'add-ember-documentation' of https://github.com/nab880/s…
nab880 Oct 30, 2024
34da91c
Revert "Update emberexample.h"
nab880 Oct 30, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/sst/elements/ember/Makefile.am
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ compdir = $(pkglibdir)
comp_LTLIBRARIES = libember.la

libember_la_SOURCES = \
example/motifs/emberexample.h
nab880 marked this conversation as resolved.
Show resolved Hide resolved
example/motifs/emberexample.cc
embergen.h \
embergen.cc \
embermap.h \
Expand Down
116 changes: 116 additions & 0 deletions src/sst/elements/ember/example/CreatingMotifs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
# C++ Ember Motifs
## Ember

[Ember](http://sst-simulator.org/SSTPages/SSTElementEmber/) is a library representing various network communications. It is often used in conjunction with motifs.

## Motif

Motifs are condensed, efficient generators for simulating different kinds of communication/computation patterns.
The motif presented here does no real work, but more detailed motifs can be found in sst-elements/src/sst/elements/ember/mpi/motifs/.

Motifs are executed as follows:

1) The motif generator is initialized (The constructor)
2) The generate function is invoked, places events on the event queue, and returns either true or false
3) The events on the event queue are processed.
4) If the generate function in step 2 returns false, go to step 2. Otherwise, the motif is complete.

Motifs are intended to be run as a 'job submission.'
The generate function models an entire iteration of an application, using the event queue to mix compute and MPI operations in every iteration.

### Register Subcomponent

Ember motifs need to be registered as an SST subcomponent. This typically happens in the header file.
For example:
```
SST_ELI_REGISTER_SUBCOMPONENT_DERIVED(
Example,
"ember",
"ExampleMotif",
SST_ELI_ELEMENT_VERSION(1,0,0),
"Performs an idle on the node. No traffic can be generated.",
SST::Ember::EmberGenerator
);
```

The parameters of this function are:

1) class associated with this Motif
3) Aspect of elements being used, in the case of Motifs, "ember."
3) Identifier of the Motif. Note that the end of this parameter must always be Motif
4) SST elements version,
5) Comment describing what the motif does
6) EmberGenerator

### Writing a constructor
```
EmberExample::EmberExample(SST::ComponentId_t id, Params& params) :
EmberMessagePassingGenerator(id, params, "Example"),

```


The constructor also reads parameters from the python script.
The params are passed through the python file in the form: `ep.addMotif("Example firstParam=100 secondParam=200")`. Note no space is allowed before or after the = operator. Parameters read from the python file will be prepended with "arg." before being passed to the C++ file. i.e. "firstParam" becomes "arg.firstParam".
The constructor can be used to perform the setup operations necessary for the generating function.

The params can be parsed in the C++ file with `firstParam = params.find<uint32_t>("arg.firstParam", 100);` where the name of the parameter is "firstParam".

### Writing a generate() function
```
bool Example::generate( std::queue<EmberEvent*>& evQ)
```
The generate function is the 'main' function of a Motif.
If the python file invokes an `addMotif`, the generating function will be invoked until the generate function returns true.
Once the generate function returns, the events queued in the evQ variable will be performed.

The generate function takes an event queue as a parameter. The event queue allows the user to include computation operations and MPI events in the simulation. Motifs are intended to be designed so that every call to generate() mimics an entire iteration of the application. The events that can be added to the event queue are listed in subsequent sections.

.

# User-defined events

These functions allow the user to control how the simulation estimates computation time.

* `enQ_compute(Queue&, uint64_t nanoSecondDelay)` -- The delay by the expected cost of the compute operation in nanoSeconds (without actually computing it)
* `enQ_compute( Queue& q, std::function<uint64_t()> func)`; -- A function is passed as a parameter and invoked. It returns a 64-bit unsigned integer that indicates the simulation delay associated with invoking the function (in nanoseconds).
* `enQ_getTime(evQ, &m_startTime)` -- sets m_startTime to the current time

There are two types of compute functions that can be enqueued.

The first computation operation takes a 64-bit integer as a parameter. This parameter is the amount of time needed in nanoseconds to perform the computation. The simulator then delays by that number of nanoseconds as if the actual computation had taken place.
The second compute takes a function as a parameter. When the event is processed, the function is invoked. The function returns the amount of time needed to perform the compute operation. The simulation is delayed by the return value of the function. The time delay could be estimated through a heuristic or measured through representative computation.


# MPI Events


We list the supported MPI events below. For more detail, see MPI API documentation.


* `enQ_init(evQ)` -- MPI initialize
* `enQ_fini(evQ)` -- MPI finalize
* `enQ_rank(evQ, m_newComm[0], &m_new_rank)` -- MPI rank
* `enQ_size(evQ, m_newComm[0], &m_new_size)` -- MPI size
* `enQ_send(evQ, x_neg, x_xferSize, 0, GroupWorld)` -- MPI send
* `enQ_recv(evQ, x_neg, x_xferSize, 0, GroupWorld)` -- MPI recv
* `enQ_isend(evQ, next_comm_rank, itemsThisPhase, 0, GroupWorld, &requests[next_request])` -- MPI isend
* `enQ_irecv(evQ, xface_down, items_per_cell * sizeof_cell * ny * nz, 0, GroupWorld, &requests[nextRequest])` -- MPI irecv
* `enQ_cancel(evQ, m_req[i])` -- MPI cancel
* `enQ_sendrecv(evQ, m_sendBuf, m_messageSize, DATA_TYPE, destRank(), 0xdeadbeef, m_recvBuf, m_messageSize, DATA_TYPE, srcRank(), 0xdeadbeef, GroupWorld, &m_resp)` -- MPI send or recv
* `enQ_wait(evQ, req)` -- MPI wait
* `enQ_waitany(evQ, m_req.size(), &m_req[0], &m_indx, &m_resp)` -- MPI waitany
* `enQ_waitall(evQ, 1, &m_req, (MessageResponse**)&m_resp)` -- MPI waitall
* `enQ_barrier(evQ, GroupWorld)` -- MPI barrier
* `enQ_bcast(evQ, m_sendBuf, m_count, DOUBLE, m_root, GroupWorld)` -- MPI broadcast
* `enQ_scatter(evQ, m_sendBuf, m_sendCnt, m_sendDsp.data(), LONG, m_recvBuf, m_count, LONG, m_root, GroupWorld)`
* `enQ_scatterv(evQ, m_sendBuf, &m_sendCnts[0], m_sendDsp.data(), LONG, m_recvBuf, m_count, LONG, m_root, GroupWorld)` -- MPI Scatter variable message size
* `enQ_reduce( evQ, m_sendBuf, m_recvBuf, m_count, DOUBLE, MP::SUM, m_redRoot, GroupWorld)`
* `enQ_allreduce(evQ, m_sendBuf, m_recvBuf, m_count, DOUBLE, m_op, GroupWorld)` -- MPI allreduce function
* `enQ_alltoall(evQ, m_sendBuf, m_colSendCnt, &m_colSendDsp_f[0], DOUBLE, m_colComm)` -- MPI alltoall with constant message size
* `enQ_alltoallv(evQ, m_sendBuf, &m_colSendCnts_f[0], &m_colSendDsp_f[0], DOUBLE, m_colComm)` -- MPI alltoall with varying message sizes
* `enQ_allgather(evQ, m_sendBuf, m_count, INT, m_recvBuf, m_count, INT, GroupWorld)` -- MPI allgather with messages of constant size
* `enQ_allgatherv(evQ, m_sendBuf, m_sendCnt, INT, m_recvBuf, &m_recvCnts[0], &m_recvDsp[0], INT, GroupWorld)` -- MPI allgather with messages of varying sizes
* `enQ_commSplit(evQ, *comm, color, key, newComm)` -- Splits the MPI comm
* `enQ_commCreate(evQ, GroupWorld, m_rowGrpRanks, &m_rowComm)` -- Creates MPI Com
* `enQ_commDestroy(evQ, m_rowComm)` --Destroys MPI comm
217 changes: 217 additions & 0 deletions src/sst/elements/ember/example/QuickStart.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,217 @@
# What is an Ember Motif?

Ember Motifs provide representative workloads and then estimate performance on hardware using SST simulations.
This guide provides a directions on how to:

* Implement a empty motif.
* Create and run motif in a SST simulation.

Implementing and running Ember Motifs requires three different files:

1. Python File
Provides information on the hardware to be simulated when running an Ember Motif
This directs SST on the available hardware components and how they are set up.
2. C++ file
Decides how the computation is structured and computed.
3. C++ header file
The header file contains primarily naming information

# Quick Start Guide

This guide gives a simple example of how to create and run a simple Motif.

First ensure SST-core and SST-elements are properly installed on your machine. For download and installation see [SST-Downloads](http://sst-simulator.org/SSTPages/SSTMainDownloads/).

Navigate to `sst-elements/src/elements/ember` inside the sst-elements library.
First, create a new directory to hold our example Motif.

`mkdir ExampleMotif`

Next, create a `ExampleMotif/exampleMotif.h` file
```
#ifndef _H_EMBER_EXAMPLE
#define _H_EMBER_EXAMPLE

#include "../../mpi/embermpigen.h"

namespace SST {
namespace Ember {

class ExampleGenerator : public EmberMessagePassingGenerator {
public:

SST_ELI_REGISTER_SUBCOMPONENT_DERIVED(
Example,
"ember",
"ExampleMotif",
SST_ELI_ELEMENT_VERSION(1,0,0),
"Performs an idle on the node, no traffic can be generated.",
SST::Ember::EmberGenerator
);

SST_ELI_DOCUMENT_PARAMS(
);

SST_ELI_DOCUMENT_STATISTICS(
{ "time-Init", "Time spent in Init event", "ns", 0},
{ "time-Finalize", "Time spent in Finalize event", "ns", 0},
{ "time-Rank", "Time spent in Rank event", "ns", 0},
{ "time-Size", "Time spent in Size event", "ns", 0},
{ "time-Send", "Time spent in Recv event", "ns", 0},
{ "time-Recv", "Time spent in Recv event", "ns", 0},
{ "time-Irecv", "Time spent in Irecv event", "ns", 0},
{ "time-Isend", "Time spent in Isend event", "ns", 0},
{ "time-Wait", "Time spent in Wait event", "ns", 0},
{ "time-Waitall", "Time spent in Waitall event", "ns", 0},
{ "time-Waitany", "Time spent in Waitany event", "ns", 0},
{ "time-Compute", "Time spent in Compute event", "ns", 0},
{ "time-Barrier", "Time spent in Barrier event", "ns", 0},
{ "time-Alltoallv", "Time spent in Alltoallv event", "ns", 0},
{ "time-Alltoall", "Time spent in Alltoall event", "ns", 0},
{ "time-Allreduce", "Time spent in Allreduce event", "ns", 0},
{ "time-Reduce", "Time spent in Reduce event", "ns", 0},
{ "time-Bcast", "Time spent in Bcast event", "ns", 0},
{ "time-Gettime", "Time spent in Gettime event", "ns", 0},
{ "time-Commsplit", "Time spent in Commsplit event", "ns", 0},
{ "time-Commcreate", "Time spent in Commcreate event", "ns", 0},
);


};
}
}

#endif /* _H_EMBER_EXAMPLE */
```
This creates a Motif generator class called ExampleGenerator that inherits from EmberMessagePassingGenerator. The Python code we provide later creates and invokes the generate function.
The SST Document Statistics provides tracking for initialization and various MPI function calls.

Motifs are executed as follows:



1) The motif generator is initialized (The contructor)
2) The generate function is invoked and returns either true or false
3) The events on the eventQueue are processed.
4) If the generate function in step 2 returned false, return to step 2, otherwise the motif is complete.

Here is a motif that returns without doing any additional work.

Then we create a file `ExampleMotif/Example.cc` with the contents:

```
#include <sst_config.h>
#include "Example.h"

using namespace SST:Ember;

ExampleGenerator::ExampleGenerator(SST::ComponentId_t id, Params& params) :
EmberMessagePassingGenerator(id, params, "Null" )
{
}

bool ExampleGenerator::generate( std::queue<EmberEvent*>& evQ)
{
// Code here is repeated until true is returned.
return true;
}
```


Motifs are intended to be ran as a 'job submission'.
The generate function models an entire iteration of an application. The event queue allows the motif to mix compute and MPI operations in every iteration.



The C++ file loads the SST:Ember namespace giving it access to other Motifs and EmberEvents.
Each Motif generator has an constructor and generate function.


Then we add the `.cc` and `.h` file to `Makefile.am`

i.e.
```
embermemoryev.h \
ExampleMotif/example.h \
ExampleMotif/example.cc \
libs/emberLib.h \
```

Finally, a python file `example.py` needs to be created:

```
from email.mime import base
import sst
from sst.merlin.base import *
from sst.merlin.endpoint import *
from sst.merlin.interface import *
from sst.merlin.topology import *

from sst.ember import *

def example():
PlatformDefinition.setCurrentPlatform("firefly-defaults")

### Setup the topology
topo = topoDragonFly()
topo.hosts_per_router = 2
topo.routers_per_group = 4
topo.intergroup_links = 2
topo.num_groups = 4
topo.algorithm = ["minimal","adaptive-local"]

# Set up the routers
router = hr_router()
router.link_bw = "4GB/s"
router.flit_size = "8B"
router.xbar_bw = "6GB/s"
router.input_latency = "20ns"
router.output_latency = "20ns"
router.input_buf_size = "4kB"
router.output_buf_size = "4kB"
router.num_vns = 2
router.xbar_arb = "merlin.xbar_arb_lru"

topo.router = router
topo.link_latency = "20ns"

### set up the endpoint
networkif = ReorderLinkControl()
networkif.link_bw = "4GB/s"
networkif.input_buf_size = "1kB"
networkif.output_buf_size = "1kB"

ep = EmberMPIJob(0,topo.getNumNodes())
ep.network_interface = networkif
ep.addMotif("Example")
ep.nic.nic2host_lat= "100ns"

system = System()
system.setTopology(topo)
system.allocateNodes(ep,"linear")

system.build()

if __name__ == "__main__":
example()
```

This follows common python syntax.
The hardware variables (topology, router and network interface) are created through assignment of a constructor
The fields of the variables are accessed using a dot operator.
Topology, router, and network interface variables need to be created for a simulation. More detailed descriptions of configuration options is in RunningMotifs.md.
Next an endpoint is created and given the motif to be used using a ep.addMotif("MotifName")call
Note multiple motifs can be added the same endpoint. The intended use for each motif to simulate an entire application. The event queue is used to simulate MPI events and computational workloads. Adding multiple motifs is useful for simulating workflows of a series of applications.

Finally, a system variable is created and 'built'

Remake SST-elements.

To run the python script

```
sst example.py
```



Loading