{"id":19865603,"url":"https://github.com/ct-clmsn/nim-sos","last_synced_at":"2025-04-09T16:20:31.796Z","repository":{"id":76760440,"uuid":"468157285","full_name":"ct-clmsn/nim-sos","owner":"ct-clmsn","description":"Nim wrapper for Sandia-OpenSHMEM","archived":false,"fork":false,"pushed_at":"2022-09-09T17:58:08.000Z","size":49,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-23T18:37:29.225Z","etag":null,"topics":["distributed-computing","high-performance-computing","hpc","nim","openshmem","productivity","supercomputing"],"latest_commit_sha":null,"homepage":"","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ct-clmsn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-10T01:54:02.000Z","updated_at":"2024-09-12T13:20:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"3e82c993-03a4-4e63-82c7-5fd6d7670191","html_url":"https://github.com/ct-clmsn/nim-sos","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ct-clmsn%2Fnim-sos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ct-clmsn%2Fnim-sos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ct-clmsn%2Fnim-sos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ct-clmsn%2Fnim-sos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ct-clmsn","download_url":"https://codeload.github.com/ct-clmsn/nim-sos/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065281,"owners_count":21041872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distributed-computing","high-performance-computing","hpc","nim","openshmem","productivity","supercomputing"],"created_at":"2024-11-12T15:23:22.311Z","updated_at":"2025-04-09T16:20:31.777Z","avatar_url":"https://github.com/ct-clmsn.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Copyright (c) 2022 Christopher Taylor                                          --\u003e\n\u003c!--                                                                                --\u003e\n\u003c!--   Distributed under the Boost Software License, Version 1.0. (See accompanying --\u003e\n\u003c!--   file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)        --\u003e\n# [nim-sos - Nim Sandia OpenSHMEM](https://github.com/ct-clmsn/nim-sos)\n\n`nim-sos` wraps the existing [SOS](https://github.com/Sandia-OpenSHMEM/SOS) OpenSHMEM library implemented by Sandia National Laboratory. `nim-sos` provides the [Nim](https://nim-lang.org) programming language distributed symmetric shared memory and Partitioned Global Address Space (PGAS) support.\n\n`nim-sos` provides a *symmetric array type* and a *symmetric scalar type*.\n\nSymmetric arrays are an extension to the existing [Nim array](https://nim-lang.org/docs/manual.html#types-array-and-sequence-types). Symmetric arrays only support values that are of [SomeNumber](https://nim-lang.org/docs/system.html#SomeNumber) types. Symmetric arrays provide element-access, slice, iterator, and partitioning support. Symmetric arrays cannot be appended to; 'add' or 'append' functionality breaks the symmetry property. Symmetric arrays are distributed and globally addressable. Symmetric arrays created with a size as part of their type are called 'symmetric static arrays'. Symmetric arrays created on the heap w/`newSymArray` are simply called symmetric arrays.\n\nSymmetric scalars are globally addressable scalar values.\n\n## SymmetricMain\n\nThe `SymmetricMain` macro detects symmetric array and symmetric scalar types during compilation and exposes them to OpenSHMEM. The `SymmetricMain` macro is a *one-stop-shop* for users. *Use of the `SymmetricMain` is mandatory*, the macro finds all symmetric types in a user's program, exposes them to OpenSHMEM, initializes and finalizes OpenSHMEM. The `SymmetricMain` macro can be used as a pragma `{.SymmetricMain.}`.\n\n```\nSymmetricMain:\n    var a = newSymArray[int]([1,2,3,4,5])\n    var b = newSymArray[int](a.len)\n\n    # pick an op to reduce\n    #\n    let rmin = reduce(minop, WORLD, b, a)\n    echo(rmin)\n```\n\n```\nproc main() {.SymmetricMain.} =\n    var a = newSymArray[int]([1,2,3,4,5])\n    var b = newSymArray[int](a.len)\n\n    # pick an op to reduce\n    #\n    let rmin = reduce(minop, WORLD, b, a)\n    echo(rmin)\n\nmain()\n```\n\n\n\n## Symmetric Arrays\n\n`nim-sos` provides a *symmetric* version of `array` data types in the tradition of [Fortran Coarrays](https://en.wikipedia.org/wiki/Coarray_Fortran). Symmetric arrays, instantiated by processing elements (PEs[1]) running in SPMD, create a global sequence partitioned across the available PEs. Symmetric arrays consist of globally addressable partitions. Users can `get` from and `put` into a remote partition of the symmetric array.\n\n[1] A PE is a program process running in SPMD on a computer or set of computers. Applications running in SPMD can run in a distributed (cluster) or a single machine setting.\n\nConsider the symmetric array `S` that is created in an SPMD program running on 2 PEs. `S` spans 2 PEs, or 2 processes residing on the same or a different machine.\n\n```\n        ---------------------------\n        -            S            -\n        -  ++++++++     ++++++++  -\n        -  + PE 0 +     + PE 1 +  -\n        -  +      +     +      +  -\n        -  +  A   +     +  B   +  -\n        -  ++++++++     ++++++++  -\n        ---------------------------\n```\n\n`S` is composed of two partitions, `A` and `B`. `A` resides in the 1st processes memory (PE 0) and `B` resides in a 2nd processes memory (PE 1). The process that contains partition `A` can 'get' a copy of the values in partition `B` using symmetric array `S` as the shared point of reference. The process that contains partition `B` can 'put' values into partition `A` using the symmetric array `S` as a shared point of reference. symmetric array operations are single-sided. PE 0 receives no notifications in the event partition `A` is modified due to a communication operation.\n\nUsers are required to define the size of each partition when creating a symmetric array. Calling the constructor `newSymArray[int](100)` for a 32 node program run will create a symmetric array with 32 partitions, each partition being 100 integers in type and length. A convenience function called `partitioner` is provided to calculate a partition size given the global number of elements that need to be stored. If a user needs a symmetric array stored on 32 nodes for 3200 integers, `partitioner` will perform the simple calculation and return 100 integers for each partition.\n\nSymmetric arrays can be instantiated either at compile-time or at runtime. Compile-time (static) symmetric arrays are called `symmetric static arrays`. Runtime (dynamic) symmetric arrays are called `symmetric arrays`. The naming convention is used to differentiate the memory allocation used to instatiate the array. To create a compile-time symmetric array, utilize the following type `symindexarray[A, B]` where `A` is an integer value denoting the size of the array to create at compile time and `B` is of `SomeNumber` type.\n\n```\nSymmetricMain:\n   var a : symsarray[100, int]\n   var b : symsarray[500, float64]\n```\n\nThe symmetric static array `a` is of type `int` and is 100 elements. The symmetric static array `b` is of type `float64` and is 500 elements.\n\nArrays declared with the `symarray[T:SomeNumber]` type are created dynamically at runtime. \n\n```\nSymmetricMain:\n    var a = newSymArray[int]([1,2,3,4,5])\n    var b = newSymArray[int](a.len)\n```\n\nThe symmetric array `a` is of type `int` and is 5 elements with values (1,2,3,4,5). The symmetric array `b` is of type `int` and is 5 elements of uninitialized values.\n\n## Symmetric Scalars\n\nSimilar to the symmetric array, except for scalar values.\n\n```\n        ---------------------------\n        -            S            -\n        -  ++++++++     ++++++++  -\n        -  + PE 0 +     + PE 1 +  -\n        -  +      +     +      +  -\n        -  +  A   +     +  B   +  -\n        -  ++++++++     ++++++++  -\n        ---------------------------\n```\n\nThe scalar value `S` is partitioned across 2 PEs. PE 0 has a scalar value `A`. PE 1 has a scalar value `B`. PE 0 can access `B` on PE 1 using the `S` scalar as a point of reference. PE 1 can access `A` on PE 0 using the `S` scalar as a point of reference.\n\nSymmetric scalar values are declared using the following types:\n\n* `symscalar[T:SomeNumber]`\n* `symint`, `symint8`, `symint16`, `symint32`, `symint64`\n* `symuint`, `symuint8`, `symuint16`, `symuint32`, `symuint64`\n* `symfloat`, `symfloat32`, `symfloat64`\n\n```\nSymmetricMain:\n   var z : symscalar[int]\n   var a : symint\n   var b : symfloat\n   var\n      cee : symint\n      d : symfloat\n```\n\nSymmetric scalars do not support the following operators `+`, `-`, `*`, `=`. Procedures have been implemented to provide support for these operators. All symmetric scalars have the following methods:\n\n* `add` : add (sum, `+`)\n* `sub` : subtract (difference, `-`)\n* `mul` : multiply (`*`)\n* `sto` : store into the local value (`=`); similar to [atomics](https://nim-lang.org/docs/atomics.html)\n* `read` : get the local value; similar to [atomics](https://nim-lang.org/docs/atomics.html)\n\nSymmetric scalar integers have the following additional operators:\n\n* `div` : integer divide\n* `mod` : integer modulo\n\nSymmetric scalar floats have the following additional operator:\n\n* `div` : integer divide\n* `/` : floating point divide\n\n### Developer Notes\n\nNew users are encouraged to review the OpenSHMEM specification [here](http://openshmem.org/site/Specification). Programs\nimplemented using `nim-sos` will require use of the [SPMD style](https://en.wikipedia.org/wiki/SPMD).\n\n### Install\n\nDownload and install [SOS](https://github.com/Sandia-OpenSHMEM/SOS)\n```\n$ ./configure --prefix=\u003cPATH_TO_INSTALL_DIR\u003e --enable-pmi-simple --disable-threads --disable-openmp --with-oshrun-launcher\n\n$ make \u0026\u0026 make install\n\n$ export LD_LIBRARY_PATH=\u003cPATH_TO_INSTALL_DIR\u003e/lib:$LD_LIBRARY_PATH\n```\n\nModify `makefile` to point `LIBDIR` and `INCDIR` to the\npath set in `\u003cPATH_TO_INSTALL_DIR\u003e`. Use the makefile to\nsee if your setup compiles.\n```\nmake\n```\n\nUse the nimble tool to install `sos`\n```\nnimble install sos\n```\n\nGenerate documentation from source\n```\nnimble doc sos\n```\n\n### Running Programs\n\n```\noshrun -n2 --mpi=pmi2 \u003cprogram_name\u003e\n```\n\nThis library is designed to be run on an HPC system that manages jobs using the following workload managers: [Slurm](https://slurm.schedmd.com), PBS, etc.\n\n### Examples\n\nThe directory 'tests/' provides several examples regarding how to utilize this library.\n\n### Licenses\n\n* Boost Version 1.0 (2022-)\n\n### Date\n\n09 March 2022\n\n### Author\n\nChristopher Taylor\n\n### Special Thanks\n\n* The OpenSHMEM developers\n* Sandia National Labs/US Department of Energy\n* The Nim community and user/developer forum\n\n### Dependencies\n\n* [nim 1.6.4](https://nim-lang.org)\n* [Sandia OpenSHMEM](https://github.com/pnnl/rofi)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fct-clmsn%2Fnim-sos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fct-clmsn%2Fnim-sos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fct-clmsn%2Fnim-sos/lists"}