diff --git a/.buildinfo b/.buildinfo new file mode 100644 index 00000000..22992bb9 --- /dev/null +++ b/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. +config: d37e3232c4f86ff1cceea14cd6659602 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml new file mode 100644 index 00000000..c4fb6fed --- /dev/null +++ b/.github/workflows/python-package.yml @@ -0,0 +1,112 @@ +# This workflow will install Python dependencies, run tests and lint with a variety of Python versions +# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions + +name: Tests + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + unit-tests: + runs-on: ubuntu-latest + env: + SPACK_MANAGER: ${{github.workspace}} + strategy: + fail-fast: false + matrix: + python-version: [3.7, 3.8, 3.9] + steps: + - uses: actions/checkout@v2 + with: + submodules: recursive + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + - name: Run unit tests + run: ./run_tests.sh + style-checks: + runs-on: ubuntu-latest + env: + SPACK_MANAGER: ${{github.workspace}} + strategy: + fail-fast: false + matrix: + python-version: [3.7] + steps: + - uses: actions/checkout@v2 + with: + submodules: recursive + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install flake8 pytest + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - name: Link scripts with flake8 + run: | + # flake8 on scripts that aren't spack extensions + flake8 . + - name: Spack Style + run: | + # check our spack extension with spack's style guide + source start.sh + spack style spack-scripting + concretization-basic: + runs-on: ${{matrix.os}} + env: + SPACK_MANAGER: ${{github.workspace}} + strategy: + fail-fast: false + matrix: + python-version: [3.7] + os: [ubuntu-latest, macos-latest] + steps: + - uses: actions/checkout@v2 + with: + submodules: recursive + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: | + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - name: Run concretization tests + run: | + source start.sh + # test and make sure the solver is working for env using clingo + spack solve exawind 1> /dev/null + tests/ci_config_concretization.py -y env-templates/exawind_basic.yaml + concretization-matrix: + runs-on: ${{matrix.os}} + env: + SPACK_MANAGER: ${{github.workspace}} + strategy: + fail-fast: false + matrix: + python-version: [3.7] + os: [ubuntu-latest] + steps: + - uses: actions/checkout@v2 + with: + submodules: recursive + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + - name: Install dependencies + run: | + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + - name: Run concretization tests + run: | + source start.sh + # test and make sure the solver is working for env using clingo + spack solve exawind 1> /dev/null + tests/ci_config_concretization.py -y env-templates/exawind_matrix.yaml diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/_images/ApplicationSpace.png b/_images/ApplicationSpace.png new file mode 100644 index 00000000..15059d82 Binary files /dev/null and b/_images/ApplicationSpace.png differ diff --git a/_images/ProfilePyramids.png b/_images/ProfilePyramids.png new file mode 100644 index 00000000..505a5330 Binary files /dev/null and b/_images/ProfilePyramids.png differ diff --git a/_images/Spack-Manager-Org.png b/_images/Spack-Manager-Org.png new file mode 100644 index 00000000..85506102 Binary files /dev/null and b/_images/Spack-Manager-Org.png differ diff --git a/_images/Spack-To-Applications.png b/_images/Spack-To-Applications.png new file mode 100644 index 00000000..53ab5fd8 Binary files /dev/null and b/_images/Spack-To-Applications.png differ diff --git a/_images/application-workflow.png b/_images/application-workflow.png new file mode 100644 index 00000000..23faf2c6 Binary files /dev/null and b/_images/application-workflow.png differ diff --git a/_sources/general/general.rst.txt b/_sources/general/general.rst.txt new file mode 100644 index 00000000..b2fb358e --- /dev/null +++ b/_sources/general/general.rst.txt @@ -0,0 +1,13 @@ +General Information +=================== + +This section is for documenting the general concepts of how Spack-Manager works, +and documentation that is applicable to all users of this software. + +.. toctree:: + :glob: + :maxdepth: 2 + + spack_manager_structure + spack_features + history diff --git a/_sources/general/history.md.txt b/_sources/general/history.md.txt new file mode 100644 index 00000000..8f90af77 --- /dev/null +++ b/_sources/general/history.md.txt @@ -0,0 +1,34 @@ +# History and inspirations for Spack-Manager + +Spack-Manager was created due to the challenges of building the complicated [Exawind](https://github.com/Exawind) software stack. +The Exawind codes have a relatively large number of TPL's and are designed to run on modern HPC architecture, which is currently a moving target. +These factors naturally lead toward using [Spack](https://github.com/spack/spack) to manage the build dependencies. + +Arguably the most common use case for Spack is software deployment. +This was the original use for Exawind developers, and a few different extra scripts were maintained for managing the build process for Exawind software. +However, during the Exawind project Spack also released features geared toward development. +This sparked the idea for the central question behind Spack-Manager: **how much of our process can we reasonably extend into the Spack ecosystem?** + +Initial evaluations of Spack's develop features were that there was potential, but also room to grow. +These features have since improved, but the other tenant of Spack-Manager was determined from this trial period: **end products need to live as independent from Spack as possible**. +This really comes down to the fact that Exawind stack was constantly changing and growing, along with Spack itself. +In reality the entire HPC and computing landscape is changing dramatically, and so our development frameworks need to be moving together, but still have room to independently flex as thing evolve. +In this sense Spack-Manager acts as a buffer in between the larger Spack project, and the invidual software projects that are using Spack-Manager to curate their development process. + +Spack-Manager's development obtained a lot of inspiration from the [Exawind-Builder](https://github.com/Exawind/exawind-builder) project. +Spack-Manager has sought to emulate some of the key features of Exawind-Builder such as the ability to use pre-configured binaries, and to allow users to quickly switch between caches. +Exawind-Builder was a tool principly designed for developers, and Spack-Manager strives to extend that user scope to the entire range of software users. + +Exawind-Builder is also another example of a tool built on-top of Spack. +However, the strategies of Spack-Manager and Exawind-Builder differ slightly in that Exawind-Builder sought to go around Spack's missing features through additional bash scripting and environment configurations, while Spack-Manager seeks to predominately extend Spack using the Spack ecosystem for these scenarios. +Both sides have pro's and con's. +Choosing to go around Spack makes it easier to customize things with fewer limitations, but it also requires additional code, interfaces and maintenance. +Choosing to conform to Spack infrastructure means accepting some of the limitations and growing pains of the Spack API, but also reducing the amount of infrastructure that needs to be maintained. +This is constantly becoming less of a sacrifice due to the quality of work done by the Spack development team. + +Spack-Manager is intended to be agile, and adapt to changes in Spack by embracing new features in Spack, and contributing back everything it can to the Spack project. +In this sense we are able to harness the pro's of Spack, while still customizing our workflow and influencing the growth of Spack in the future. + + + + \ No newline at end of file diff --git a/_sources/general/spack_features.md.txt b/_sources/general/spack_features.md.txt new file mode 100644 index 00000000..4b324e60 --- /dev/null +++ b/_sources/general/spack_features.md.txt @@ -0,0 +1,155 @@ +# Important Spack Features + +## Spack Specs + +In Spack the idea of a _spec_ is very important. Specs are descriptors of particular aspects or configurations of a package or packages. +Specs can completely general, merely denoted the name of a package, or they can very specific such as specifying the name of the package with a particular version, with a particular compiler and compiler version, with specific options called _variants_, as well as constraints on dependencies of the package. +Spack's documentation has much more information on specs [here](https://spack.readthedocs.io/en/latest/basic_usage.html#specs-dependencies), but we summarize them here as it is important to utilizing Spack. +Specs are a loose or general form of a configuration for a package. However, Spack is very exact it how it will build and satisfy your requested spec. +It does this through the process of _concretization_. Concretization maps a spec, no matter how general or specific, into an _exact_ graph of +how Spack will build and fulfill the spec. A command for understanding this process is the `spack spec` command. Using `spack spec` +will report to the user how Spack will create a concrete graph or DAG of the package on its dependencies. For example: + +``` +% spack spec zlib +Input spec +-------------------------------- +zlib + +Concretized +-------------------------------- +zlib@1.2.11%apple-clang@12.0.0+optimize+pic+shared arch=darwin-catalina-skylake +``` + +Here we intend to install the zlib package which has no dependencies. If we specify nothing but `zlib`, this is the configuration Spack has solved +in which it will fulfill the installation of zlib. We can be more specific about our request. Looking at what compilers are available for us in Spack +we can use: +``` +% spack compilers +==> Available compilers +-- apple-clang catalina-x86_64 ---------------------------------- +apple-clang@12.0.0 + +-- gcc catalina-x86_64 ------------------------------------------ +gcc@11.2.0 +``` + +Here we are on a MacOS computer and we have two compilers available. If I prefer `zlib` be installed using gcc, one can use: +``` +% spack spec zlib%gcc +Input spec +-------------------------------- +zlib%gcc + +Concretized +-------------------------------- +zlib@1.2.11%gcc@11.2.0+optimize+pic+shared arch=darwin-catalina-skylake +``` + +Notice Spack honored our compiler constraint request. Spack reports the concretized spec in a manner that continues to itself be a spec: +``` +% spack spec zlib@1.2.11%gcc@11.2.0+optimize+pic+shared arch=darwin-catalina-skylake +Input spec +-------------------------------- +zlib@1.2.11%gcc@11.2.0+optimize+pic+shared arch=darwin-catalina-skylake + +Concretized +-------------------------------- +zlib@1.2.11%gcc@11.2.0+optimize+pic+shared arch=darwin-catalina-skylake +``` + +Therefore using the `spec` command helps us to understand specs and what Spack will do with a spec before we use them in other commands. +Here is an example of a more complicated package: +``` +% spack spec amr-wind +Input spec +-------------------------------- +amr-wind + +Concretized +-------------------------------- +amr-wind@main%apple-clang@12.0.0~cuda~fortran+hypre+internal-amrex~ipo~masa+mpi+netcdf~openfast~openmp~rocm+shared+tests+unit build_type=Release arch=darwin-catalina-skylake + ^cmake@3.22.2%apple-clang@12.0.0~doc+ncurses+openssl+ownlibs~qt build_type=Release arch=darwin-catalina-skylake + ^ncurses@6.2%apple-clang@12.0.0~symlinks+termlib abi=none arch=darwin-catalina-skylake + ^pkgconf@1.8.0%apple-clang@12.0.0 arch=darwin-catalina-skylake + ^openssl@1.1.1m%apple-clang@12.0.0~docs certs=system arch=darwin-catalina-skylake + ^perl@5.34.0%apple-clang@12.0.0+cpanm+shared+threads arch=darwin-catalina-skylake + ^berkeley-db@18.1.40%apple-clang@12.0.0+cxx~docs+stl patches=b231fcc4d5cff05e5c3a4814f6a5af0e9a966428dc2176540d2c05aff41de522 arch=darwin-catalina-skylake + ^bzip2@1.0.8%apple-clang@12.0.0~debug~pic+shared arch=darwin-catalina-skylake + ^diffutils@3.8%apple-clang@12.0.0 arch=darwin-catalina-skylake + ^libiconv@1.16%apple-clang@12.0.0 libs=shared,static arch=darwin-catalina-skylake + ^gdbm@1.19%apple-clang@12.0.0 arch=darwin-catalina-skylake + ^readline@8.1%apple-clang@12.0.0 arch=darwin-catalina-skylake + ^zlib@1.2.11%apple-clang@12.0.0+optimize+pic+shared arch=darwin-catalina-skylake + ^hypre@2.23.0%apple-clang@12.0.0~complex~cuda~debug+int64~internal-superlu~mixedint+mpi~openmp+shared~superlu-dist~unified-memory arch=darwin-catalina-skylake + ^netlib-lapack@3.9.1%apple-clang@12.0.0~external-blas~ipo+lapacke+shared~xblas build_type=Release arch=darwin-catalina-skylake + ^openmpi@4.1.2%apple-clang@12.0.0~atomics~cuda~cxx~cxx_exceptions+gpfs~internal-hwloc~java~legacylaunchers~lustre~memchecker~pmi~pmix+romio~singularity~sqlite3+static~thread_multiple+vt+wrapper-rpath fabrics=none schedulers=none arch=darwin-catalina-skylake + ^hwloc@2.7.0%apple-clang@12.0.0~cairo~cuda~gl~libudev+libxml2~netloc~nvml~opencl~pci~rocm+shared arch=darwin-catalina-skylake + ^libxml2@2.9.12%apple-clang@12.0.0~python arch=darwin-catalina-skylake + ^xz@5.2.5%apple-clang@12.0.0~pic libs=shared,static arch=darwin-catalina-skylake + ^libevent@2.1.12%apple-clang@12.0.0+openssl arch=darwin-catalina-skylake + ^openssh@8.8p1%apple-clang@12.0.0 arch=darwin-catalina-skylake + ^libedit@3.1-20210216%apple-clang@12.0.0 arch=darwin-catalina-skylake + ^netcdf-c@4.7.4%apple-clang@12.0.0~dap~fsync~hdf4~jna+mpi+parallel-netcdf+pic+shared patches=2c88dfbd6d339a0336a43b14a65a1d1df995b853b645e4af612617612a642a53 arch=darwin-catalina-skylake + ^hdf5@1.10.7%apple-clang@12.0.0+cxx~fortran+hl~ipo~java+mpi+shared~szip~threadsafe+tools api=default build_type=RelWithDebInfo patches=2a1e3118d7d3d7411820e567b03530de96a46385304017f8e548408aa1cfbfc0 arch=darwin-catalina-skylake + ^m4@1.4.19%apple-clang@12.0.0+sigsegv patches=9dc5fbd0d5cb1037ab1e6d0ecc74a30df218d0a94bdd5a02759a97f62daca573,bfdffa7c2eb01021d5849b36972c069693654ad826c1a20b53534009a4ec7a89 arch=darwin-catalina-skylake + ^libsigsegv@2.13%apple-clang@12.0.0 arch=darwin-catalina-skylake + ^parallel-netcdf@1.12.2%apple-clang@12.0.0~burstbuffer+cxx+fortran+pic+shared arch=darwin-catalina-skylake +``` + +It is obvious concretized specs can get large quite quickly. However, Spack is very good at standing on it's own without requirements +from the existing system. Therefore it can be quite straightforward to build complicated packages on many machines. However, it can also be argued +that this situation involves many packages with Spack will build that may already exist on the machine. While this is fair, we typically solve +this by specifying `externals` which make Spack aware of packages already existing on the system and utilizing them in its DAG. Spack-manager +has machine-specific configurations provided by its contributors for this purpose. Obtaining a configuration for Spack for the specific machine +and specific project will save the user of Spack a lot of time. + +In our previous concretized DAG, `amr-wind` has dependencies on packages. Dependencies in specs are denoted with `^`. We can use this to constrain dependencies we would like to request. +For example here we put a constraint on the cmake version: +``` +% spack spec amr-wind ^cmake@3.17.0 +Input spec +-------------------------------- +amr-wind + ^cmake@3.17.0 + +Concretized +-------------------------------- +amr-wind@main%apple-clang@12.0.0~cuda~fortran+hypre+internal-amrex~ipo~masa+mpi+netcdf~openfast~openmp~rocm+shared+tests+unit build_type=Release arch=darwin-catalina-skylake + ^cmake@3.17.0%apple-clang@12.0.0~doc+ncurses+openssl+ownlibs~qt build_type=Release patches=1c540040c7e203dd8e27aa20345ecb07fe06570d56410a24a266ae570b1c4c39,bf695e3febb222da2ed94b3beea600650e4318975da90e4a71d6f31a6d5d8c3d,e51119dd387aa3eb2f21fee730d3aa8b5480301c5e2e3a33bd86f4f7d8903861 arch=darwin-catalina-skylake + ^ncurses@6.2%apple-clang@12.0.0~symlinks+termlib abi=none arch=darwin-catalina-skylake +... +``` +Concretization is an NP-hard problem, so solving the DAG is not instantaneous, and it is very much an active area of research. Spack has +gone through one iteration thus far of updating its concretization strategy. This is the difference between the "original" concretizer and the newer clingo concretizer. + +Another important idea in Spack is describing the configuration of a particular package involving a complicated DAG into a succint string for the installation directory of the package for example. To do this, Spack collapses several properties of the DAG into a _hash_. Spack then uses this hash to provide a short form mapping for a particular package and its full description. Spack is a very powerful database of software installations and can be queried to understand the exact state of each package and pinpointing a specific package in which the user is interested. We leave these to the Spack documentation to continue. + + +## Spack Commands + +Spack has many commands, many of which have great information when adding `-h` to them. Here we list a few of the most important commands for using within Spack-Manager. + + - `spack spec -I `: solve the DAG for the spec and show packages in the DAG that are already installed + - `spack location -i `: used for finding the specific location of an installed package + - `spack concretize -f `: force an activated environment to undergo concretization + - `spack install `: install all packages listed in an environment's `spack.yaml` file + - `spack uninstall `: uninstall specific spec + - `spack uninstall --dependencies -a -y `: uninstall everything related to a general spec (`-a`) and all its dependencies without confirming + - `spack cd -b `: change to build directory of package + - `spack env activate -d ` or `spacktivate -d `: activate a Spack environment at specified path + - `spack develop `: develop source code in a package locally + - `spack help --all `: list all available Spack commands + - `spack list `: list all available Spack packages matching the string + - `spack find `: query Spack's database of installed packages + - `spack find -Lvd `: list the hashes, variants, and dependencies of the provided spec + - `spack stage && spack cd `: download the package's source code and extract it for browsing + - `spack docs`: open the online spack documentation in a browser + - `spack -d `: get debug info on exactly what Spack is doing when it fails + - `spack config blame packages`: show exactly where Spack is obtaining its preferences for things like concretization + - `spack compilers`: list the compilers in which Spack is aware + + +## Spack Knowledgebase + +In each package installation directory in `spack/opt` Spack keeps a `.spack` directory which contains information on exactly how the package was built. diff --git a/_sources/general/spack_manager_structure.rst.txt b/_sources/general/spack_manager_structure.rst.txt new file mode 100644 index 00000000..ac0ed1d2 --- /dev/null +++ b/_sources/general/spack_manager_structure.rst.txt @@ -0,0 +1,49 @@ +Spack-Manager Structure +======================= + +Spack-Manager is a Spack extension that provides a way for software applications +to configure their usage of spack. + +.. figure:: ./application-workflow.png + :width: 100% + + An example of generalized infrastructure requirements that are common across HPC and scientific computing applications. Spack-Manager's goal is to empower these types of infrastructures while still allowing application teams to drive the details. + +The code of Spack-Manager is independent of each individual application and each +application code needs to configure a Spack-Manager `Project` to tell Spack-Manager how to work +with their application. + +.. figure:: ./Spack-Manager-Org.png + :width: 50% + + Spack-Manager is designed to provide an abstraction that can support multiple application teams. Each team develops a Project that can be registered with an instance of Spack-Manager. + +A `Project` at its core is simply a collection of `spack configuration files`_ and `spack package repositories`_. +A few other optional hooks will be discussed below. + +The configuration files in a `Project` are organized based on the configuration bifurcations that the projects supports. +These are called `Machines` based on the guiding principle that spack configurations typically have to be +changed when the machine/system is changed. + +`Projects` can be registered with Spack-Manager by adding them to the `spack-manager.yaml` configuration file. +This file lives in the Spack-Manager directory and controls settings for `Spack-Manager` and the `Projects` that +are registered. + +.. code-block:: yaml + + spack-manager: + projects: + - /path/to/project_a + default_view: False + - $HOME/project_b + +Information on configuring a new `Project` can be found in the system administrator profile documentation `here`_. + +.. figure:: ./ApplicationSpace.png + :width: 100% + + The end goal of many code application and DevOps teams is to efficiently span the space of platform permutations and project variations. + +.. _spack configuration files: https://spack.readthedocs.io/en/latest/configuration.html +.. _spack package repositories: https://spack.readthedocs.io/en/latest/repositories.html +.. _here: https://sandialabs.github.io/spack-manager/user_profiles/system_admins/creating_a_project.html diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt new file mode 100644 index 00000000..9cdc794b --- /dev/null +++ b/_sources/index.rst.txt @@ -0,0 +1,70 @@ +=============== + Spack-Manager +=============== + + +`Spack-Manager `_ is a light-weight extension to +`Spack `_ that is intended to streamline the software development and deployment cycle +for software projects on specific machines. +A given software project typically has multiple configurations across many machines. +Spack-Manager is quite literal in its name, in that it provides a way to manage and organize these configurations +across multiple machines, and multiple projets. + +.. figure:: ./Spack-To-Applications.png + :width: 75% + + Spack is serving the package management needs of thousands of software packages. + However, individual application teams wish to harness the power of Spack for their individual applications specific needs. + This naturally leads to redundant, similar workflows. + +The intent of this project is to maintain as thin of a buffer as possible between software packages and Spack, and to be pushing ideas and workflow +improvements back to Spack on a regular basis to reduce the code that is maintained here. +As such we do not try to fully mask Spack's workflow or commands from users, but rather expose them at a level appropriate for the user type. + +User Profiles +============= + +Spack-Manager's design is intended to serve three separate user types in a software project, and the level of expected spack exposure/knowledge required +decreases as the user becomes further removed from the build process. The three user profiles are: + +- System administrators (Spack is heavily exposed and relied on) +- Code developers (some basics about Spack are required, but much of the workflow can be scripted away) +- Analysts (zero exposure to Spack) + +.. figure:: ./ProfilePyramids.png + :width: 70% + + Population size of each profile is inverserly proportional to the Spack knowledge required for their roles + +Separate documentation exists for each of these user profiles. + +.. toctree:: + :maxdepth: 4 + + user_profiles/user_profiles + +Benefits of Spack-Manager +========================= + +- Spack-Manager allows additional agility and coordination at the project level that can not be maintained for a larger tool/database such as Spack. + This is done through heavy use of custom Spack `package repositories `_ and + Spack's `custom extensions `_ to allow for prototyping at the project level, as well as the option to + maintain features that are only intended for the project's development team. + +- Spack-Manager maximizes overlap between the workflows of the three user profiles. + The main thought behind Spack-Manager is that the exact same infrastructure that the system administrators use to deploy binaries and modules on various machines + can be recycled to run nightly tests, generate time stamped snapshots of binaries for developers to link against, and supply end users + with production executables. + This framework is stitched together through Spack, but the end products (binaries and modules) are designed to be as independent from Spack as possible. + +- Spack-Manager provides the benefits of Spack by seeking to maintain as small of a wrapper layer as possible. Some of these benefits include: + - Build reproducibiilty, and scalability + - Buy-in and feedback from HPC vendors and software developers over thousands of projects + - Support options, extended documentation and testing through the much larger Spack project + +Additional details about the philosophy, and general knowledge can be found in the following documentation section. + +.. toctree:: + :maxdepth: 3 + + general/general diff --git a/_sources/user_profiles/analysts/analysts.md.txt b/_sources/user_profiles/analysts/analysts.md.txt new file mode 100644 index 00000000..c8361894 --- /dev/null +++ b/_sources/user_profiles/analysts/analysts.md.txt @@ -0,0 +1,19 @@ +# Analysts Documentation + +This documentation is for people who just want to run the software on preconfigured machines. + +Spack-Manager deploys software through modules. The Spack-Manager infrastructure is designed to create time-stamped snapshots. Typically this will be done by system-administrators, but anyone building software can create snapshot modules or custom modules that can be shared. + +To use modules you need to add the location of the module files to your `MODULEPATH` environment variable. These are typically stored in the `$SPACK_MANAGER/modules` directory. You can execute the command +``` +module use [path/to/modules] +``` +to add the Spack generated modules to the list of available modules in your environment. + +The location of these module files on the major machines are: + +| Machine Name | Path | +|--------------|------| +| snl-hpc | `/projects/wind/spack-manager/modules` | +| cee | `/projects/wind/spack-manager/modules` | +| eagle | `/projects/exawind/exawind-snapshots/modules` | diff --git a/_sources/user_profiles/developers/advanced_topics.md.txt b/_sources/user_profiles/developers/advanced_topics.md.txt new file mode 100644 index 00000000..0c549b83 --- /dev/null +++ b/_sources/user_profiles/developers/advanced_topics.md.txt @@ -0,0 +1,205 @@ +# Advanced Topics for Developers + +This section is designed to go over some of the tips and tricks for developers +that will help you improve your workflow and handle some more nuanced scenarios. + +## Handling Multiple Environments +Spack-Manager is designed to support multiple environments from a single Spack +instance. +This allows common libraries to be reused between installations. +Where you place the environments is entirely up to you. +There is a default location `$SPACK_MANAGER/environments` where the environments +will be created if you pass the `--name` or `-n` flag into one of the environment +creation commands. +Using the `--directory` or `-d` argument will create the environment at the local +path you specify. +Omitting either of these arguments will lead to the environment being created in +the current working directory. + +In terms of when to create an environment, our recommendation is that an environment +be created for each unique concept you are working on, and once that concept is finalized +you uninstall the software and/or delete the environment. + +## Cleaning Up Old Environments +If an environment is stale and hasn't been used in a while, our recommendation +is to create a new environment using it's `spack.yaml` and then just delete the +old environment. + +An example of how to do this is: + +```console +quick-create -d [location of new env] -y [old environment]/spack.yaml +spack -e [old environment] uninstall --all +rm -rf [old environment] +``` +> **TIP:** Using `spack -e [env location]` allows you to run commands in that environment +without activating it in your shell. + +If you truly wish to revise the environment then it is a good idea to try and reconcretize +before making changes to the environment. `spack concretize -f`. + +## Modifying Specs in an Environment +Once an environment is active in your shell it can still be modified. +The definition of the environment is in the `spack.yaml` file and modifying this +will modify the environment. +So to add a variant, such as making the build a debug build, simply open the `spack.yaml` +in your environment's directory and add `build_type=Debug` to the spec for the package +you want to be built in debug mode. + +> **TIP:** Spack has a built in command for automatically opening the `spack.yaml` file in a +text editor for you. It is `spack config edit`. The default editor is Vim, but you can set it to be anything you want simply by setting the `EDITOR` environment variable i.e. `export EDITOR=emacs`. + +A more archaic way to do this from the command line would be to remove the spec +and then add it back with the edits that you want. + +For example say you have `amr-wind@master+openfast+hypre` as the spec in your environment. +You could run +```console +spack rm amr-wind@master +spack add amr-wind@master+openfast+hypre build_type=Debug +``` +if you really don't want to open the yaml file. +This is discouraged though because it involves more typing and is prone to more errors. +All users are encouraged to become comfortable reading and editing the `spack.yaml` file. +The ones generated by Spack-Manager are quite small and only contain information pertinent +to you as an end user. + +## Debugging Spack Errors +It is inevitable that you will encounter some error from Spack while using Spack-Manager. +Spack-Manager is a dynamic tool that tries to stay up-to-date with Spack's new features. +Sometimes we catch bugs and sometimes there are incompatibilities or inconsistencies +in the state of your Spack installation. + +We suggest the following steps for how to handle an error from Spack: + +1) If you just updated Spack-Manager make sure the Spack submodule is up-to-date: `git submodule update` +2) Read the error message again and see if it makes sense. Many of the error messages are quite good. +3) Run `sm-clean`. This is a heavy clean up command for Spack-Manager that we've created based on the errors we've seen in the past. +4) Run your Spack command with the `-d` flag (debug) i.e. `spack -d install` and see if that gives you any more insight +5) Reach out for help on slack, github issues or email. + +## When and How to Use Multiple Instances of Spack-Manager +Sometimes it is useful to have multiple instances of Spack-Manager. +Some examples of when it would be a good idea to do this: +- You have multiple machines on a shared filesystem and they are conflicting, or one is problematic while the other is stable. +- You want to archive production environments/builds and separate them from your software development work. +- You are developing features for Spack or Spack-Manager and want to keep it separate from the rest of your work. + +The key concept here is that there is something stable and something more dynamic. +It is useful to blow away everything in dynamic software development and start from scratch periodically. + +Spack-Manager has been designed to be self-contained and to not create or use dependencies from other Spack +instances as much as possible. +The key thing is you don't want to mix Spack instances in the same shell. +So to use different Spack-Manager instances you just need to make sure that the `SPACK_MANAGER` environment variable +is set to the right instance and that you don't switch things up in the same shell. + +An example of how this can be done in a `bashrc` is: +```bash +# Load dynamic spack-manager for software development +function development-spack-manager(){ + export SPACK_MANAGER=/path/to/my/dynamic/spack-manager + source ${SPACK_MANAGER}/start.sh + spack-start +} + +# Load stable builds +function production-spack-manager(){ + export SPACK_MANAGER=/path/to/my/production/spack-manager + source ${SPACK_MANAGER}/start.sh + spack-start +} +``` + +In this example the different Spack-Manager instances can be loaded in a new shell by calling separate functions. + +## Strategies for Conserving Disk Space +If Spack is not periodically pruned it can become a storage hog. +When doing software development Spack will create and preserve the build directory for develop specs, +and then it will install the binaries in the common Spack install tree. + +To prune your local build directories you can simply run `rm -rf spack*` inside a build directory. +This will remove all the files and directories Spack created but not modify your source code. +It is essentially just removing the CMake build directory and all of Spack's logs. +If you are frequently modifying specs for your environment (switch from Release to Debug) then you +will notice several build directories `spack-build-[hash]`. +Preserving these allows for incremental builds, and deleting them will cause you to rebuild the entire software product. +So there is a trade off between waiting on builds and storage space. + +To handle the issue of install trees we've added the `--local-source` or `-l` flag to the environment creation commands. +This will make it so all the binaries are installed local to the environment in a directory named `opt/`. +Now when you delete the environment you will also delete all the install binaries and you don't need to worry about them piling up in the +main Spack install tree. + +However, if you only use this option you will end up rebuilding all the binaries in every environment. +Using `--local-source` means that the environment can't doesn't see any of the other environments and you will need to create a link between them. +To link to your main Spack database create the `$SPACK_MANAGER/configs/user/upstreams.yaml` file and put the following inside of it: +```yaml +upstreams: + root_spack: + install_tree: $spack/opt/spack +``` +Any files added to the `$SPACK_MANAGER/configs/user` directory will automatically be added to the environments you create going forward. +This allows users to set configurations like upstreams or personal preferences without needing to have them get pushed to the main repo. +The addition above makes it so any `--local-source` environment you create can reuse binaries from your main install tree. + +So to setup a very space conservative Spack-Manager repo you should do the following: +1) Create a base environment and install the software you want to use without using `--local-source` +2) Create the `upstreams.yaml` file as specified above. +3) Create all development environments with the `--local-source` or `-l` flag. + +Now whenever you want to clean things up just delete your development environment directory and all the space from that specific build will be removed. +Doing this is a bit tedious and the new base environments will need to be periodically created for new compilers and flags, or the existing ones will need to be updated. + +## Constructing and Utilizing Multiple builds +One of the nice features about using Spack is the build environments you setup can have arbitrary complexity. +A nice feature for this is to setup your development environment to perform multiple builds that you may need +from the same source such as a `+cuda` and `~cuda` build, or `Release` and `Debug` builds. + +To do this you need to edit the `spack.yaml` file so that the `concretizer:unify` parameter is set to `false`. +`Unify` tells the concretizer that all the software has to concretize into a single graph. +We turn on unification by default in Spack-Manager to serve as a guard-rail for users and to simply syntax for setting up environments. + +```yaml +spack: + # having the two specs + specs: + - nalu-wind@master+hypre+cuda + - nalu-wind@master+hypre~cuda + view: false + concretizer: + unify: false # this is defaulted to true + include: + - include.yaml + develop: + nalu-wind: + # this develop spec matches both the root specs and so the source code will be used for both + spec: nalu-wind@master + ``` + + You may not want to rebuild both instances of the code every time you make a change. + However, you can do `build-env-dive nalu-wind~cuda` if you want to develop the code on a non-cuda environment for the faster link times. + When using `build-env-dive` you can simply call `make`, `make clean`, run the tests, etc from inside the build directory. +When you want to test the cuda build you can exit the build-env and rebuild the Cuda case. +An example of this workflow is illustrated below. + +```console +# Setup the environment +quick-create -d two-build-one-env -s nalu-wind+cuda nalu-wind~cuda +spack manager develop nalu-wind@master +spack config add conncretizer:unify:false # a way to edit the spack.yaml configs from the command line +spack install +# dive into the non-cuda build environment +build-env-dive nalu-wind~cuda +# make some code changes +[...] +# run the unit-tests and interate +make -j8 && ./unittestX +# jump out of the build0-env +exit +# now rebuild everything with the changes +spack install +# check the cuda tests +build-env-dive nalu-wind+cuda +ctest -R unit -VV +``` diff --git a/_sources/user_profiles/developers/developer_spack_minimum.md.txt b/_sources/user_profiles/developers/developer_spack_minimum.md.txt new file mode 100644 index 00000000..3ecf308d --- /dev/null +++ b/_sources/user_profiles/developers/developer_spack_minimum.md.txt @@ -0,0 +1,219 @@ +# Developers: What you need to know about Spack + +Developers who are using Spack-Manager as their build system need to know some basic things about Spack +to effectively utilize the tool. +We've tried to minimize the required knowledge you need to retain for commands, but it is important to +understand the fundamental concepts of Spack to obtain autonomy in your basic workflow and communicate +effectively when looking for help. + +The most critical concepts to learn for development are: +1. [Querying the Spack commands](#querying-the-spack-commands): `spack info` and `--help` +2. [Reading and writing Spack specs](#reading-and-writing-spack-specs) +3. [The major steps of the Spack build process](#major-steps-of-the-spack-build-process) + +## Querying the Spack commands + +The first item in this list is also arguably the most important. +A large array of questions about Spack can be answered by simply using the `-h` or `--help` flags +for the commands. Every Spack command has this feature and this will print a short +description of the what the command does along with all the options the command takes. +For example: +``` +spack cd -h +usage: spack cd [-h] [-m | -r | -i | -p | -P | -s | -S | --source-dir | -b | -e [name]] ... + +cd to spack directories in the shell + +positional arguments: + spec package spec + +optional arguments: + --source-dir source directory for a spec (requires it to be staged first) + -P, --packages top-level packages directory for Spack + -S, --stages top level stage directory + -b, --build-dir build directory for a spec (requires it to be staged first) + -e [name], --env [name] + location of the named or current environment + -h, --help show this help message and exit + -i, --install-dir install prefix for spec (spec need not be installed) + -m, --module-dir spack python module directory + -p, --package-dir directory enclosing a spec's package.py file + -r, --spack-root spack installation root + -s, --stage-dir stage directory for a spec +``` +Prints all the information you need to know about how to use the command `spack cd`. + +Spack-Manager has emulated this behavior by adding the `-h`/`--help` flags to all of the commands including shell commands. +So if you see a command you don't understand, or if you ever forget the syntax for a command, the first starting point is the `-h` flag. + +Along with the `-h` command, the other querying command that every developer should know is `spack info`. +`spack info [package name]` gives you all the information for a spec. Specifically for developers, this will tell you the versions and variants in the queried package. + +For example `spack info amr-wind` gives: +``` +spack info amr-wind +CMakePackage: amr-wind + +Description: + None +Homepage: https://github.com/Exawind/amr-wind + +Maintainers: @jrood-nrel @michaeljbrazell + +Externally Detectable: + False + +Tags: + ecp ecp-apps + +Preferred version: + main [git] https://github.com/Exawind/amr-wind.git on branch main + +Safe versions: + main [git] https://github.com/Exawind/amr-wind.git on branch main + +Deprecated versions: + None + +Variants: + Name [Default] When Allowed values Description + =========================== ======= ==================== ================================== + + amdgpu_target [none] +rocm none, gfx1011, AMD GPU architecture + gfx906, gfx802, + gfx701, gfx803, + gfx1010, gfx900, + gfx801, gfx1012, + gfx908, gfx90a + asan [off] -- on, off Turn on address sanitizer + build_type [RelWithDebInfo] -- Debug, Release, CMake build type + RelWithDebInfo, + MinSizeRel + clangtidy [off] -- on, off Turn on clang-tidy + cppcheck [off] -- on, off Turn on cppcheck + cuda [off] -- on, off Build with CUDA + cuda_arch [none] +cuda none, 32, 35, 10, CUDA architecture + 86, 72, 62, 61, 70, + 21, 50, 11, 12, 37, + 52, 30, 75, 53, 60, + 20, 13, 80 + hypre [on] -- on, off Enable Hypre integration + internal-amrex [on] -- on, off Use AMRex submodule to build + ipo [off] -- on, off CMake interprocedural optimization + masa [off] -- on, off Enable MASA integration + mpi [on] -- on, off Enable MPI support + netcdf [on] -- on, off Enable NetCDF support + openfast [off] -- on, off Enable OpenFAST integration + openmp [off] -- on, off Enable OpenMP for CPU builds + rocm [off] -- on, off Enable ROCm support + shared [on] -- on, off Build shared libraries + tests [on] -- on, off Activate regression tests + unit [on] -- on, off Build unit tests + +Installation Phases: + cmake build install + +Build Dependencies: + amrex cmake cuda hip hsa-rocr-dev hypre llvm-amdgpu masa mpi netcdf-c openfast py-matplotlib py-pandas + +Link Dependencies: + amrex cuda hip hsa-rocr-dev hypre llvm-amdgpu masa mpi netcdf-c openfast py-matplotlib py-pandas + +Run Dependencies: + None + +Virtual Packages: + None +``` + +So if you want to know how to create a debug build, you can look at this information and see: +``` +build_type [RelWithDebInfo] -- Debug, Release, CMake build type + RelWithDebInfo, + MinSizeRel +``` +This is an list spec and the available options are listed. +So adding `build_type=Debug` to the spec i.e. `amr-wind build_type=Debug` will create a debug build. +If you want to turn on `masa`, you can add `+masa`. +This will be covered in more detail in the [next section](#reading-and-writing-spack-specs) when specs are discussed. +For this section it is sufficient to know that `spack info` is the key to knowing what you need to write to customize your builds. + +## Reading and writing Spack specs + +Spack specs are critical to using Spack-Manager because they are the language used to communicate the options and configurations of +the software that is getting built. +We provide an overview of what a spec is, and the parts that go into making a Spack spec in our +[general documentation](https://sandialabs.github.io/spack-manager/general/spack_features.html#spack-specs), +and an even more thorough description can be found in the +[spack documentation](https://spack.readthedocs.io/en/latest/basic_usage.html#specs-dependencies) + +A simple description of a spec for this section can be understood by looking at delimiters in a spec: `{name}@{version}%{compiler}{variants} ^{dependent specs}`. +- `name` is the package name. This is what you query with the `spack info` and is typically the name of the software. +- `version` is what immediately follows the `@` symbol. This can be aligned to a github branch, tag, or a url (i.e. download a tar file). The details for the versions can be found via the `spack info command` +- `compiler` specification is what immediately follows the `%` symbol, and typically also has a name and version i.e. `gcc@9.3.0` +- `variants` are the flags for the software. They can be booleans (where `+` is on and `~` is off) and lists i.e `build_type=Release` or `cuda_arch=70` +- `dependent specs` are the ways to specify flags for the dependencies. Whenever a `^` is added it is delimiting to a new spec with the restriction that must be in the dependency graph of the first spec or _root spec_. + +We don't recommend developers use the `^` command at all since it makes things more confusing, and is unnecessary for normal development cycles. +It is addressed here for clarity and completeness, but you won't need them unless you intend to build multiple version of the same software in the same environment. +An example of this would be an environment that builds the same software with multiple compilers, but this is typically a feature for system administrators, not standard development cycles. + +## Major steps of the Spack build process + +Spack-Manager uses [Spack environments](https://spack.readthedocs.io/en/latest/environments.html) to manage your development builds. +These environments are similar to Conda environments in concept, but they benefit from re-using software that you've built in previous environments. +As such it is recommended that you maintain a single instance of Spack-Manager to organize and curate your builds, and create new environments when you want to start a new development project. For example if you are working on multiple features at the same time it is convenient to maintain multiple environments. + +Understanding the steps that go into creating an environment is helpful for debugging and thinking about how to organize your workflow. +Spack and Spack-Manager are also relatively easy to script in either bash or python, +but it is important to understand the build process to write effective scripts. + +The major steps and associated commands for building software with Spack environments are (don't forget to [query the commands](#querying-the-spack-commands) to learn more about them): +1. **Create the environment:** (`spack manager create-env`) + This generates a `spack.yaml` file which is how the environment is defined. Most of the following commands will be manipulating this file. +2. **Activate the environment:** (`spack env activate`) + This sets the environment as active in your shell. +3. **Add root specs:** (`spack add`) + Define the software that you want in the environment. Spack will solve for the dependencies of all these root specs, and ensure that your environment meshes together. They just need the `name` as a minimum. +4. **Add develop specs** (`spack develop`) + Determine what software you want to modify i.e. which specs you want to develop. + These specs must have the `name` and `version` as a minimum. + They are not going to be added to your environment by themselves, but rather serve as keys for the concretizer to determine if a spec should be treated as a develop spec or not. + Essentially, if the concretizer can determine that a spec in the graph can be equivalenced with the develop spec, then it will use your source code and not spack's usual process for cloning/building/installing. + Think of this as a sort of dictionary. + For instance `spack add trilinos` and `spack develop trilinos@develop` will mean that trilinos will use the source code, + but if you had done `spack add trilinos@master` then it would not because `trilinos@develop` and `trilinos@master` can't be equivalenced. + It is recommended that you always just do `name@version` for your develop specs to get the broadest match possible. + More documentation on this can be found in the [spack documentation](https://spack-tutorial.readthedocs.io/en/latest/tutorial_developer_workflows.html). +5. **Concretize:** (`spack concretize`) + This is how the Spack determines what the dependency graph needs to look like for your environment. It is a non-trivial problem to solve since you can use any combination of variants in each package in the [DAG](https://en.wikipedia.org/wiki/Directed_acyclic_graph). Each software package can enforce built in conflicts that are set by the maintainers, but anything that is not constrained by your spec or the software itself will fall to the default (once again look to `spack info` to see the defaults). +6. **Build/install:** (`spack install`) + Now that you've decided what combination of software you want to build, what elements you want to develop, and what the dependency graph is all that is left is to build and install. Easy right? + +This may seem like a lot to go over, and this was not a very thorough description of each step. +These steps are covered with a workflow example in the [developer tutorial](https://sandialabs.github.io/spack-manager/user_profiles/developers/developer_workflow.html) +where we walk through each step one at a time. +The intention of this page is to serve as an introduction and a reference going forward. +If you forget a step or command you can always come back to this page to see what it is and see a brief description of the whole process. +It is also important to know that in your practical workflow you won't need to type out each command every time you want to use Spack-Manager. +Spack-Manager contains convenience scripts that wrap the steps together, and print them as they execute to help you remember them. + +The two most hands off commands are: + +- `quick-create-dev`: this will do steps 1-5 for you automatically if you provide specs with versions in the input arguments (stops at step 4 if you don't) +- `quick-activate`: this will activate a previously created environment for you. You just pass the directory location to it. + +For example, fastest way to start developing `amr-wind` and `openfast` together is: + +``` +quick-create-dev --name my-dev-project --spec amr-wind@main+openfast openfast@master +# go to amr-wind source code +spack cd amr-wind # modify the code in here as you wish +# go to openfast source code +spack cd openfast # modify the code in here as you wish +# install code +spack install +``` + +As a reminder, to learn more about the commnands used above `quick-create-dev --help`, `spack cd --help`, `spack install --help`. +To learn what other build options you have for `amr-wind` ... `spack info amr-wind`, `openfast` ... `spack info openfast`, etc. diff --git a/_sources/user_profiles/developers/developer_workflow.md.txt b/_sources/user_profiles/developers/developer_workflow.md.txt new file mode 100644 index 00000000..8bf1c989 --- /dev/null +++ b/_sources/user_profiles/developers/developer_workflow.md.txt @@ -0,0 +1,232 @@ +# Quick-Start: Developer Workflow + +In this section we will go over the developer work flow in Spack-Manager using the [quick-functions](https://psakievich.github.io/spack-manager/user_profiles/developers/useful_commands.html). + +This tutorial assumes you are familiar with the [3 things developers need to know](https://psakievich.github.io/spack-manager/user_profiles/developers/developer_spack_minimum.html). +If you are unfamiliar with these 3 things then please review the documentation before proceeding. + +The developer workflow will be covered in 4 stages: +1) [Setting up Spack-Manager](#setup-spack-manager) +2) [Create an environment for development](#creating-an-environment) +3) [Building and making code changes](#building-and-making-code-changes) +4) [Running tests and coming back](#running-tests-and-coming-back) + +There is also the [quick start](#quick-start) below that just lists all the commands for you in a row. + +## Setup Spack-Manager +Setting up Spack-Manager should be a 1 time thing on a given machine. +First pick directory you want to store Spack-Manager. +The ideal location for this directory is one that has adequate storage for multiple build environments, +and it should also be on a filesytem that is accesible where you plan to run the software. + +```console +git clone --recursive git@github.com:sandialabs/spack-manager.git +``` +For the purpose of this documentaiton we will define a `SPACK_MANAGER` environment variable, +and it should provide the absolute path to your Spack-Manager directory. +Spack-Manager also provides a `spack manager location` command which will provide an absolute path +to the Spack-Manager source directory. +To have access to the +commands we will use in this tutorial you need to source `$SPACK_MANAGER/scripts/quick_commands.sh`. +This script enables all the shell functions in Spack-Manager but it does not activate Spack. +We do this to allow you to add these lines to your `bash_profile` without any penalty +since sourcing Spack adds an unacceptable level of overhead for standard shell spawning, + +```console +# These lines can be added to your bash_profile +export SPACK_MANAGER=$(pwd)/spack-manager +source $SPACK_MANAGER/scripts/quick_commands.sh +``` + +## Creating an Environment + +With the Spack development workflow we are going to create an environment similar to a Conda environment. +Setting up the environments is a multistep process that is outlined in greater detail [here](https://sandialabs.github.io/spack-manager/user_profiles/developers/snapshot_workflow.html) and [here](https://sandialabs.github.io/spack-manager/user_profiles/developers/useful_commands.html#environment-setup-process). +There are three `quick-commands` for creating environments: `quick-create`, `quick-create-dev` and `quick-develop`. +They all exit the process of setting up an environment at different points in the process as outlined below: + +| Step | quick-create | quick-create-dev | quick-develop | +|:-----|:------------:|:----------------:|:-------------:| +| Create an environment | x | x | x| +| Activate an environment | x | x | x | +| Add root specs | x | x | x| +| Add develop specs | | x | x | +| Add externals | | | x | +| Concretize and install | | | | + +For developers we recommend using `quick-create-dev` and `quick-develop` depending on if you want to use externals or not. + +The interface for both of these commands is exactly the same. Moving forward we will use `quick-create-dev` in this example. +To see the options for the command we can run it with the `--help` command. + +```console +quick-create-dev -h +************************************************************* +HELP MESSAGE: +quick-create-dev sets up a developer environment +where all specs are develop specs that will be automatically cloned +from the default repos + +The next typical steps after running this command are to add externals if +you want them, or run spack install. + +The base command and it's help are echoed below: + + ++ spack manager create-dev-env -h +usage: spack manager create-dev-env [-h] [-m MACHINE] [-d DIRECTORY | -n NAME] [-y YAML] [-s SPEC [SPEC ...]] + +optional arguments: + -d DIRECTORY, --directory DIRECTORY + Directory to copy files + -h, --help show this help message and exit + -m MACHINE, --machine MACHINE + Machine to match configs + -n NAME, --name NAME Name of directory for environment (managed environment) + -s SPEC [SPEC ...], --spec SPEC [SPEC ...] + Specs to populate the environment with + -y YAML, --yaml YAML Reference spack.yaml to copy to directory +************************************************************* +``` + +The main flags to use for standard developer workflow are the `--name` or `--directory` flags and the `--spec` flags. + +To set up a build of the exawind driver where we are developing `amr-wind` and `nalu-wind` too we would run: + +```console +quick-create-dev -n example-env -s exawind@master nalu-wind@master amr-wind@main +``` +If you don't want to develop one of these packages (say you're only focused on `amr-wind`) then just ommit the software you don't +plan to develop in from the spec list in the command above. Please note that these specs need to be concrete specs, meaning they have the name +(`amr-wind`) and the version from spack (`main`), and that **that the version is not necessarily the same thing as the branch**. +This is covered in the [things developers need to know about Spack](https://sandialabs.github.io/spack-manager/user_profiles/developers/developer_spack_minimum.html) for those needing a refresher. + +The `-n` flag can be replaced with `-d` if we want to setup an environment in a different location than `spack:config:environments_root` (see the [spack documentation](https://spack.readthedocs.io/en/latest/config_yaml.html#spack-settings-config-yaml) for help on configuring custom managed spack environment locaitons). +The `quick-create-dev` command will execute all the stages in the table above including cloning the repos from github for the software. +These clones of the source code default to the environment directory you specified with the `-d` or `-n` flags. +If we wish to work off specific branches then we can use `git add remote`, `git fetch` and `git checkout` to get the branches we want +inside each of the clones before building. + +### Managing the Source Code + +There are 4 options for setting up the source code you will use in your development process +1) Allow spack to clone the default git repo and branch when you use the `spack develop` or `spack manager develop` commands. +2) Use the `spack manager develop` command with the `--repo-branch` argument to clone from a specific fork and branch. +3) Pre-clone the source code into the environment directory. +4) Use additional `develop` arguments to point spack to exisiting source code outside the environment directory. + +Option 1 happens automatically if you run `quick-create-dev`. Option 2 can be used with an active environment. +See below for an example of how to use option2. + +```console +# create an environment and acticate it with "quick-create" +# then clone the "amr-feature" branch from a user specific fork of the amr-wind git repo +# then clone the "openfast-feature" branch from a user specific fork of the openfast git repo +# finally build the software using the source code that was just cloned +quick-create -n build-from-my-fork -s amr-wind+openfast +spack manager develop --repo-branch git@github.com:psakievich/amr-wind.git amr-feature amr-wind@main +spack manager develop --repo-branch git@github.com:psakievich/openfast.git openfast-feature openfast@master +spack install +``` + +If you wish to pre-clone your repos using option 3 you can simply create a directory, +pre-clone the software you want to develop with names that match the package names and run your `quick-create-dev` inside the directory you created without either of the `-d` or `-n` flags. +This is because the default behavior of the command is to create the environment files, and clone repos in the current +working directory. + +For example: +```console +mkdir test && cd test +# note that we name the clone of exawind-driver 'exawind' in the clone process to match the spack package name +git clone --recursive --branch main git@github.com:Exawind/exawind-driver.git exawind +git clone --recursive --branch master git@github.com:Exawind/nalu-wind.git +git clone --recursive --branch main git@github.com:Exawind/amr-wind.git +quick-create-dev -s exawind@main amr-wind@main nalu-wind@master ++ spack manager create-dev-env -s exawind@master amr-wind@main nalu-wind@master +==> Configuring spec exawind@master for development at path exawind +==> Warning: included configuration files should be updated manually [files=include.yaml] +==> Configuring spec amr-wind@main for development at path amr-wind +==> Configuring spec nalu-wind@master for development at path nalu-wind ++ spack env activate --dir /current/working/directory --prompt +``` +does the same thing as +```console +quick-create-dev -d test -s exawind@master nalu-wind@master amr-wind@main +``` +However, adding in the extra pre-clone steps gives you a little more control over your environment. + +Options 1 and 2 are the recommended ways of proceeding since they are the most concise and support the most common use cases. +Option 3 is available if you need additional flexibility, are on an air gaped system +or have issues with spack cloning from git (this may be due to an old version of git on the system). +Option 4 is not really recommended but the curious can learn more by diving into spack's documentation and/or using `spack manager develop --help` +to learn the features and combinations available. + +At this point in the process your environment is active and all setup. +You can confirm that it is active with `spack env status` which displays the active environment. + +## Building and Making Code Changes +Once the environment is setup and active you can simply run +```console +spack install +``` +to build the software. + +In this case we are building without externals so you will see `clingo` get bootstrapped, concretization happen, and then the install occur for the entire software stack. + +You are free to make code changes in any of the code directories. +Re-running `spack install` will cause Spack to check for changes by inspecting the time-date stamp on the files in the source code directories. +If they are newer than the install time then it will trigger an incremental build to capture any changes that might exist. +Any changes you make in a dependency will also trigger a rebuild of the upstream software too. +In this environment if you make a change in `amr-wind` it will also trigger a rebuild of the `exawind` package as well. + +If you wish to just do a quick incremental build you can use the `spack manager make` command: +```console +spack manager make amr-wind -j=16 +``` + +## Running Tests and Coming Back + +To run tests in a one off manner you can use the `spack build-env` command to run commands in a sub-shell with the build environment. +This is further documented [here](https://sandialabs.github.io/spack-manager/user_profiles/developers/snapshot_workflow.html#running). +We also have a function `build-env-dive` which is a beta feature that launches this same subshell in your terminal and dives into it. +It is further documented [here](https://sandialabs.github.io/spack-manager/user_profiles/developers/useful_commands.html#build-env-dive). +Finally, if a `test` target is implementd for your software you can use `spack manager make` +```console +spack manager make --args="test -j16" amr-wind +``` + +If you wish to come back to an environment later, or in a new shell you can just run +```console +quick-activate /path/to/the/environment/you/wish/to/activate +``` +and this will do all the activation for the environment for you. +You will be able to come back at anytime and pick up where you left off. + +## Quick Start +These are the commands needed to set up Spack-Manager and a development build for the exawind-driver with the intention of editing `nalu-wind` and `amr-wind` at the same time. +```console +# setup Spack-Manager +git clone --recursive git@github.com:sandialabs/spack-manager.git +export SPACK_MANAGER=$(pwd)/spack-manager +source $SPACK_MANAGER/start.sh +# setup environment +quick-create-dev -n demo -s exawind@master amr-wind@main nalu-wind@master +# build code +spack install +# code changes in amr-wind +spack cd amr-wind +# .... make code changes +# code changes in nalu-wind +spack cd nalu-wind +# ... make code changes +# re-build +spack install +# go to build directory +spack cd -b nalu-wind +# run all the overset regression tests in nalu-wind +spack build-env nalu-wind ctest -R overset +# run regression tests in the exawind-driver +build-env-dive exawind +ctest -VV +# don't forget you need to exit this build env subshell when you're done by calling `exit` +``` diff --git a/_sources/user_profiles/developers/developers.rst.txt b/_sources/user_profiles/developers/developers.rst.txt new file mode 100644 index 00000000..c6377d32 --- /dev/null +++ b/_sources/user_profiles/developers/developers.rst.txt @@ -0,0 +1,15 @@ +Developer Documentation +======================= + +Developers in this section are softare developers for the projects that are using Spack-Manager. +This documentation is to help understand the basic requirements and workflow for developing software using Spack-Manager. + +.. toctree:: + :glob: + :maxdepth: 4 + + developer_spack_minimum + developer_workflow + useful_commands + advanced_topics + snapshot_workflow diff --git a/_sources/user_profiles/developers/snapshot_workflow.md.txt b/_sources/user_profiles/developers/snapshot_workflow.md.txt new file mode 100644 index 00000000..ae12828d --- /dev/null +++ b/_sources/user_profiles/developers/snapshot_workflow.md.txt @@ -0,0 +1,340 @@ +# Snapshot Developer Workflow Example + +**WARNING:** This documentation is fairly specific to ExaWind and has not been generalized for an arbitrary `Spack-Manager` project. +THe information is still useful. However, you may not translate directly or be able to follow along. + + +In this tutorial we will look at how to setup a developer workflow using snapshots if they are provided on your machine. + +## Setup + +We use the Eagle machine at NREL for the example, and we choose to develop both the `hypre` and `nalu-wind` +projects for running on the GPU using CUDA. Starting from nothing, we first clone Spack-Manager: +``` +[user@el1 ~]$ export SCRATCH=/scratch/${USER} +[user@el1 ~]$ cd ${SCRATCH} +[user@el1 user]$ git clone --recursive https://github.com/sandialabs/spack-manager.git +Cloning into 'spack-manager'... +remote: Enumerating objects: 2610, done. +remote: Counting objects: 100% (2610/2610), done. +remote: Compressing objects: 100% (1001/1001), done. +remote: Total 2610 (delta 1345), reused 2476 (delta 1256), pack-reused 0 +Receiving objects: 100% (2610/2610), 426.10 KiB | 4.14 MiB/s, done. +Resolving deltas: 100% (1345/1345), done. +Submodule 'spack' (https://github.com/spack/spack) registered for path 'spack' +Cloning into '/lustre/eaglefs/scratch/user/spack-manager/spack'... +remote: Enumerating objects: 354065, done. +remote: Total 354065 (delta 0), reused 0 (delta 0), pack-reused 354065 +Receiving objects: 100% (354065/354065), 155.14 MiB | 22.08 MiB/s, done. +Resolving deltas: 100% (150589/150589), done. +Submodule path 'spack': checked out '3576e5f3d6b34d8bc8c8c8f2749127ece1ce89be' +``` + +We then activate Spack-Manager: +``` +[user@el1 user]$ export SPACK_MANAGER=${SCRATCH}/spack-manager && source ${SPACK_MANAGER}/start.sh && spack-start +``` + +Once Spack-Manager itself is activated, we create the Spack environment in which we will install and develop. +To do this we use the `spack manager create-env` command. +Our environment will be called `exawind` using the `--name` argument. We will choose to focus on building Nalu-Wind using the spec +`nalu-wind@master+hypre+cuda %gcc`, which means, `nalu-wind` at the `master` branch, with hypre +enabled (`+hypre`), and CUDA (`+cuda `), using the GCC compiler (`%gcc`, which without a version, selects the default compiler version). +``` +[user@el1 user]$ spack manager create-env --name exawind --spec 'nalu-wind@master+hypre+cuda %gcc' +making /scratch/user/spack-manager/environments/exawind +``` + +Once the environment is created, we need to activate it: +``` +[user@el1 user]$ spack env activate -d ${SPACK_MANAGER}/environments/exawind +``` +Both of the previous steps can be combined into one with `quick-create-env -n exawind -s 'nalu-wind@master+hypre+cuda %gcc'`. + +Next, we will turn `nalu-wind` and `hypre` into "develop specs" with a command that tells Spack we want to edit the code for these packages +locally and always rebuild with our local clones of the packages. We do this with the `spack manager develop` command: +``` +[user@el1 user]$ spack manager develop nalu-wind@master; spack manager develop hypre@develop +==> Configuring spec nalu-wind@master for development at path nalu-wind +==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml] +==> Configuring spec hypre@develop for development at path hypre +==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml] +``` + +The `develop` command clones both of our packages into the `${SPACK_MANAGER}/environments/exawind` directory. It is possible to specify other locations +of these package repos if they are already cloned by using the `-p` option for specifying a path. If we want to let Spack clone, we +can always switch our remotes and branches within the repos cloned by Spack by doing something like the following: +``` +[user@el1 user]$ cd ${SPACK_MANAGER}/environments/exawind/nalu-wind +[user@el1 nalu-wind]$ git remote -v +origin git@github.com:Exawind/nalu-wind.git (fetch) +origin git@github.com:Exawind/nalu-wind.git (push) +[user@el1 nalu-wind]$ git remote add mine git@github.com:user-nrel/nalu-wind.git +[user@el1 nalu-wind]$ git remote rm origin +[user@el1 nalu-wind]$ git remote rename mine origin +[user@el1 nalu-wind]$ git pull +remote: Enumerating objects: 15, done. +remote: Counting objects: 100% (14/14), done. +remote: Compressing objects: 100% (4/4), done. +remote: Total 15 (delta 10), reused 14 (delta 10), pack-reused 1 +Unpacking objects: 100% (15/15), 2.78 KiB | 237.00 KiB/s, done. +From github.com:user-nrel/nalu-wind + * [new branch] jroverf/NonTemplateNodalGradPOpenBC -> origin/jroverf/NonTemplateNodalGradPOpenBC + * [new branch] master -> origin/master + * [new branch] update_golds_10_26_2021 -> origin/update_golds_10_26_2021 +There is no tracking information for the current branch. +Please specify which branch you want to merge with. +See git-pull(1) for details. + + git pull + +If you wish to set tracking information for this branch you can do so with: + + git branch --set-upstream-to=origin/ master + +[user@el1 nalu-wind]$ git branch --set-upstream-to=origin/master master +Branch 'master' set up to track remote branch 'master' from 'origin'. +[user@el1 nalu-wind]$ git pull +Already up to date. +[user@el1 nalu-wind]$ git checkout update_golds_10_26_2021 + +Branch 'update_golds_10_26_2021' set up to track remote branch 'update_golds_10_26_2021' from 'origin'. +Switched to a new branch 'update_golds_10_26_2021' +[user@el1 nalu-wind]$ git branch + master +* update_golds_10_26_2021 +``` + +Next, we decide how to take advantage of the prebuilt snapshots on the machine. Here we use the `spack manager external` +command to specify a "view" in which we want to pull external packages into our environment. Snapshots are organized by date. +With the `--latest` flag, Spack-Manager will find the latest snapshot available on your machine automatically. Here we will use the latest snapshot +and one that is attributed to our GCC with CUDA configuration, called `gcc-cuda`. Views are typically organized by compiler, +e.g. `intel`, `clang`, `gcc`, and +`gcc-cuda`, etc. We will need to "blacklist" any packages we plan on developing locally, but this happens automatically for packages +we have already set as develop specs. +``` +[user@el1 user]$ spack manager external --latest -v gcc-cuda +==> Warning: included configuration files should be updated manually [files=include.yaml] +``` + +## Building + +Once our externals and git clones are configured, we have the necessary `*.yaml` files in our `${SPACK_MANAGER}/environments/exawind` environment directory +to "concretize" and (re)install our entire project. The `spack.yaml` file in this directory is the main yaml file in which the +other yaml files are included. Concretizing is required to solve or map our loosely defined `nalu-wind@master+hypre+cuda %gcc` spec into "concrete" parameters of our dependency graph (or DAG). The concrete DAG is _exactly_ how Spack will fulfill the dependencies for your spec. We +concretize with the command (we almost always want to use the force with `-f`). It will likely complain about us using the "original" concretizer, but this will be fixed in the future: +``` +[user@el1 user]$ spack concretize -f +==> Warning: the original concretizer is currently being used. + Upgrade to "clingo" at your earliest convenience. The original concretizer will be removed from Spack starting at v0.18.0 +==> Concretized nalu-wind@master%gcc+cuda+hypre + - rbzxf3n nalu-wind@master%gcc@9.3.0~asan~boost~catalyst+cuda~fftw+hypre~ipo~openfast+pic~rocm+tests~tioga~wind-utils abs_tol=1e-15 build_type=Release cuda_arch=70 cxxstd=14 dev_path=/scratch/user/spack-manager/environments/exawind/nalu-wind rel_tol=1e-12 arch=linux-centos7-skylake_avx512 + - b5pippu ^cmake@3.22.1%gcc@9.3.0~doc+ncurses+openssl+ownlibs~qt build_type=Release arch=linux-centos7-skylake_avx512 + - cwar5vn ^cuda@11.2.2%gcc@9.3.0~allow-unsupported-compilers~dev arch=linux-centos7-skylake_avx512 + - ukbdvpe ^hypre@develop%gcc@9.3.0~complex+cuda~debug+fortran~gptune~int64~internal-superlu~mixedint+mpi~openmp+shared~superlu-dist+unified-memory cuda_arch=70 dev_path=/scratch/user/spack-manager/environments/exawind/hypre arch=linux-centos7-skylake_avx512 + - ypwgjj2 ^mpt@2.22%gcc@9.3.0 arch=linux-centos7-skylake_avx512 + - g4tc7v2 ^netlib-lapack@3.9.1%gcc@9.3.0~external-blas~ipo+lapacke+shared~xblas build_type=Release arch=linux-centos7-skylake_avx512 + - sp3klcm ^kokkos-nvcc-wrapper@3.2.00%gcc@9.3.0+mpi arch=linux-centos7-skylake_avx512 + - 5agjw2c ^nccmp@1.9.0.1%gcc@9.3.0~ipo build_type=Release arch=linux-centos7-skylake_avx512 + - p2fnhpz ^netcdf-c@4.7.4%gcc@9.3.0~dap~fsync~hdf4~jna+mpi+parallel-netcdf+pic+shared patches=2c88dfbd6d339a0336a43b14a65a1d1df995b853b645e4af612617612a642a53 arch=linux-centos7-skylake_avx512 + - uyq6mxb ^trilinos@develop%gcc@9.3.0~adios2~amesos+amesos2~anasazi~aztec~basker+belos+boost~chaco~complex+cuda+cuda_rdc~debug~dtk~epetra~epetraext~epetraextbtf~epetraextexperimental~epetraextgraphreorderings+exodus+explicit_template_instantiation~float+fortran+gtest+hdf5~hypre~ifpack+ifpack2~intrepid~intrepid2~ipo~isorropia+kokkos~mesquite~minitensor~ml+mpi+muelu~mumps~nox~openmp~phalanx~piro~python~rocm~rol~rythmos~sacado~scorec+shards~shared~shylu+stk~stk_unit_tests~stokhos~stratimikos~strumpack~suite-sparse~superlu~superlu-dist~teko~tempus+tpetra~trilinoscouplings+wrapper~x11+zoltan+zoltan2 build_type=Release cuda_arch=70 cxxstd=14 dev_path=/projects/exawind/exawind-snapshots/spack-manager/environments/exawind/snapshots/eagle/2022-01-26/trilinos gotype=long patches=ffdad9a639ff490da5bd4f254e3a849b9dbf39cf7d28f8ed4419a05048846cf6 arch=linux-centos7-skylake_avx512 + - ci73hai ^yaml-cpp@0.6.3%gcc@9.3.0~ipo+pic+shared~tests build_type=Release arch=linux-centos7-skylake_avx512 + +==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml] +``` + +Once our environment is concretized, we don't have to concretize again unless we change some configuration in the `*.yaml` files. +Concretization is also not explicity required for the next `spack install` command, but if any `*.yaml` files are changed, it is +recommended to `spack concretize -f`. +So now we are able to install our project with the simple command: +``` +[user@el1 user]$ spack install +==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml] +==> Installing environment /scratch/user/spack-manager/environments/exawind +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external cmake-3.22.1-b5pippuk6fzbpysv24phtw4etslotbs6) +[+] /nopt/nrel/ecom/hpacf/compilers/2020-07/spack/opt/spack/linux-centos7-skylake_avx512/gcc-8.4.0/cuda-11.2.2-5muy3vijyqputqmbdyzhltqot3fvwibu (external cuda-11.2.2-cwar5vnomowwdorf57nay6e7erladdby) +==> mpt@2.22 : has external module in ['mpt/2.22', 'slurm'] +[+] /opt/hpe/hpc/mpt/mpt-2.22 (external mpt-2.22-ypwgjj2akokavha4jkpqm4prylh2vmjr) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netlib-lapack-3.9.1-g4tc7v27alixmh2ail3lud3iweclbf52) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external kokkos-nvcc-wrapper-3.2.00-sp3klcmwurgk2hrye2tpgjv5x2pq3tlq) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external nccmp-1.9.0.1-5agjw2cs2kprcw2xm5ffmrojfc7aknnz) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netcdf-c-4.7.4-p2fnhpzbpg7wtriqqsbudgtdwgtcrud3) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external trilinos-develop-uyq6mxbuc2lw3oext626lbmyiiyh7bqf) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external yaml-cpp-0.6.3-ci73hainzvjnag2ynsg7jxvaotnflzal) +==> Installing hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 +==> No binary for hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 found: installing from source +==> No patches needed for hypre +==> hypre: Executing phase: 'autoreconf' +==> hypre: Executing phase: 'configure' +==> hypre: Executing phase: 'build' +==> hypre: Executing phase: 'install' +==> hypre: Successfully installed hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 + Fetch: 0.00s. Build: 4m 30.38s. Total: 4m 30.38s. +[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 +==> Installing nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx +==> No binary for nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx found: installing from source +==> No patches needed for nalu-wind +==> nalu-wind: Executing phase: 'cmake' +==> nalu-wind: Executing phase: 'build' +==> nalu-wind: Executing phase: 'install' +==> nalu-wind: Successfully installed nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx + Fetch: 0.00s. Build: 32m 27.59s. Total: 32m 27.59s. +[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx +``` + +We notice that both `nalu-wind` and `hypre` are being rebuilt, while the rest of the dependency graph is fullfilled through the externals defined from +the selected snapshot. Now that we have built and installed our first iteration of the development cycle. We can pursue editing of code +and iterate easily on a simplified build process. + +## Editing Code + +We start by verifying our currently activated environment in Spack: +``` +[user@el1 user]$ spack find +==> In environment /scratch/user/spack-manager/environments/exawind +==> Root specs +-- no arch / gcc ------------------------------------------------ +nalu-wind@master%gcc +cuda+hypre + +==> 9 installed packages +-- linux-centos7-skylake_avx512 / gcc@9.3.0 --------------------- +cuda@11.2.2 hypre@develop mpt@2.22 nalu-wind@master nccmp@1.9.0.1 netcdf-c@4.7.4 netlib-lapack@3.9.1 trilinos@develop yaml-cpp@0.6.3 +``` + +Next we will edit code in `hypre`: +``` +[user@el1 user]$ cd ${SPACK_MANAGER}/environments/exawind/hypre +[user@el1 hypre]$ echo "//" >> src/HYPRE_parcsr_mgr.c +``` + +Then we can simply rebuild and install the entire project by: +``` +[user@el1 hypre]$ spack install +==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml] +==> Installing environment /scratch/user/spack-manager/environments/exawind +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external cmake-3.22.1-b5pippuk6fzbpysv24phtw4etslotbs6) +[+] /nopt/nrel/ecom/hpacf/compilers/2020-07/spack/opt/spack/linux-centos7-skylake_avx512/gcc-8.4.0/cuda-11.2.2-5muy3vijyqputqmbdyzhltqot3fvwibu (external cuda-11.2.2-cwar5vnomowwdorf57nay6e7erladdby) +==> mpt@2.22 : has external module in ['mpt/2.22', 'slurm'] +[+] /opt/hpe/hpc/mpt/mpt-2.22 (external mpt-2.22-ypwgjj2akokavha4jkpqm4prylh2vmjr) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netlib-lapack-3.9.1-g4tc7v27alixmh2ail3lud3iweclbf52) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external kokkos-nvcc-wrapper-3.2.00-sp3klcmwurgk2hrye2tpgjv5x2pq3tlq) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external nccmp-1.9.0.1-5agjw2cs2kprcw2xm5ffmrojfc7aknnz) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netcdf-c-4.7.4-p2fnhpzbpg7wtriqqsbudgtdwgtcrud3) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external trilinos-develop-uyq6mxbuc2lw3oext626lbmyiiyh7bqf) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external yaml-cpp-0.6.3-ci73hainzvjnag2ynsg7jxvaotnflzal) +==> Installing hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 +==> No binary for hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 found: installing from source +==> No patches needed for hypre +==> hypre: Executing phase: 'autoreconf' +==> hypre: Executing phase: 'configure' +==> hypre: Executing phase: 'clean' +==> hypre: Executing phase: 'build' +==> hypre: Executing phase: 'install' +==> hypre: Successfully installed hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 + Fetch: 0.00s. Build: 4m 26.05s. Total: 4m 26.05s. +[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 +==> Installing nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx +==> No binary for nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx found: installing from source +==> No patches needed for nalu-wind +==> nalu-wind: Executing phase: 'cmake' +==> nalu-wind: Executing phase: 'build' +==> nalu-wind: Executing phase: 'install' +==> nalu-wind: Successfully installed nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx + Fetch: 0.00s. Build: 1m 33.13s. Total: 1m 33.13s. +[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx +==> Warning: Module file /lustre/eaglefs/scratch/user/spack-manager/spack/share/spack/modules/linux-centos7-skylake_avx512/nalu-wind-master-gcc-9.3.0-rbzxf3n exists and will not be overwritten +``` + +Notice both `hypre` and `nalu-wind` are rebuilt. Since `nalu-wind` depends on `hypre`, it is rebuilt in order, and `nalu-wind` is relinked to `hypre`. +Spack also performed the `make install` step and the binaries are installed to regular Spack paths in `${SPACK_MANAGER}/spack/opt`. So the binaries can be referenced from the installed directory or from the build directories in each project in `${SPACK_MANAGER}/environments/exawind`. + +Next we can edit code in `nalu-wind` as well, and rebuild the project: +``` +[user@el1 hypre]$ cd ${SPACK_MANAGER}/environments/exawind/nalu-wind +[user@el1 nalu-wind]$ echo "//" >> unit_tests.C +[user@el1 nalu-wind]$ spack install +==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml] +==> Installing environment /scratch/user/spack-manager/environments/exawind +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external cmake-3.22.1-b5pippuk6fzbpysv24phtw4etslotbs6) +[+] /nopt/nrel/ecom/hpacf/compilers/2020-07/spack/opt/spack/linux-centos7-skylake_avx512/gcc-8.4.0/cuda-11.2.2-5muy3vijyqputqmbdyzhltqot3fvwibu (external cuda-11.2.2-cwar5vnomowwdorf57nay6e7erladdby) +==> mpt@2.22 : has external module in ['mpt/2.22', 'slurm'] +[+] /opt/hpe/hpc/mpt/mpt-2.22 (external mpt-2.22-ypwgjj2akokavha4jkpqm4prylh2vmjr) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netlib-lapack-3.9.1-g4tc7v27alixmh2ail3lud3iweclbf52) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external kokkos-nvcc-wrapper-3.2.00-sp3klcmwurgk2hrye2tpgjv5x2pq3tlq) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external nccmp-1.9.0.1-5agjw2cs2kprcw2xm5ffmrojfc7aknnz) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netcdf-c-4.7.4-p2fnhpzbpg7wtriqqsbudgtdwgtcrud3) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external trilinos-develop-uyq6mxbuc2lw3oext626lbmyiiyh7bqf) +[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external yaml-cpp-0.6.3-ci73hainzvjnag2ynsg7jxvaotnflzal) +[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 +==> Installing nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx +==> No binary for nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx found: installing from source +==> No patches needed for nalu-wind +==> nalu-wind: Executing phase: 'cmake' +==> nalu-wind: Executing phase: 'build' +==> nalu-wind: Executing phase: 'install' +==> nalu-wind: Successfully installed nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx + Fetch: 0.00s. Build: 1m 27.78s. Total: 1m 27.78s. +[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx +==> Warning: Module file /lustre/eaglefs/scratch/user/spack-manager/spack/share/spack/modules/linux-centos7-skylake_avx512/nalu-wind-master-gcc-9.3.0-rbzxf3n exists and will not be overwritten +``` +Notice since nothing has changed in `hypre`, only `nalu-wind` was necessary to rebuild. We can continue to edit code and iterate simply by using the `spack install` command to rebuild the entire project concisely. + +## Running + +Lastly, to run the code we typically want to enter the build directory and run an executable using the environment in which it was built. +We do this by doing the following where we run the `nalu-wind` unit tests as an example. While on a compute node on the Eagle machine: +``` +[user@r103u23 ~]$ spack cd -b nalu-wind +[user@r103u23 spack-build-rbzxf3n]$ spack build-env nalu-wind ./unittestX + Nalu-Wind Version: v1.2.0 + Nalu-Wind GIT Commit SHA: e9142052b09d6a6ddecbe9b83dedd1f7b4588fac-DIRTY + Trilinos Version: 13.1-ga66bb9c6fa4 + +[==========] Running 478 tests from 116 test suites. +[----------] Global test environment set-up. +[----------] 1 test from Basic +[ RUN ] Basic.CheckCoords1Elem +[ OK ] Basic.CheckCoords1Elem (1 ms) +[----------] 1 test from Basic (2 ms total) + +[----------] 5 tests from BasicKokkos +[ RUN ] BasicKokkos.discover_execution_space + +Kokkos::Cuda is available. +Default execution space info: macro KOKKOS_ENABLE_CUDA : defined +macro CUDA_VERSION = 11020 = version 11.2 +Kokkos::Cuda[ 0 ] Tesla V100-PCIE-16GB capability 7.0, Total Global Memory: 15.78 G, Shared Memory per Block: 48 K : Selected +Kokkos::Cuda[ 1 ] Tesla V100-PCIE-16GB capability 7.0, Total Global Memory: 15.78 G, Shared Memory per Block: 48 K + +[ OK ] BasicKokkos.discover_execution_space (0 ms) +[ RUN ] BasicKokkos.simple_views_1D +[ OK ] BasicKokkos.simple_views_1D (2 ms) +[ RUN ] BasicKokkos.simple_views_2D +[ OK ] BasicKokkos.simple_views_2D (2 ms) +[ RUN ] BasicKokkos.parallel_for +[ OK ] BasicKokkos.parallel_for (1 ms) +``` + +One can also obtain a bash shell with the package's build environment for performing many tasks by doing: +``` +spack cd -b nalu-wind +bash -rcfile ../spack-build-env.txt +``` + +## Iterating + +After the initial setup overhead is in place. The process for iterating in the code development can be summarized as such: +``` +[user@el1 user]$ export SPACK_MANAGER=${SCRATCH}/spack-manager && source ${SPACK_MANAGER}/start.sh && spack-start && spack env activate -d ${SPACK_MANAGER}/environments/exawind +[user@el1 user]$ #edit code +[user@el1 user]$ spack install +[user@el1 user]$ spack cd -b package && spack build-env package ./exe +[user@el1 user]$ #edit code +[user@el1 user]$ spack install +[user@el1 user]$ spack cd -b package && spack build-env package ./exe +[user@el1 user]$ #edit spack.yaml +[user@el1 user]$ spack concretize -f +[user@el1 user]$ spack install +[user@el1 user]$ spack cd -b package && spack build-env package ./exe +... +``` diff --git a/_sources/user_profiles/developers/useful_commands.md.txt b/_sources/user_profiles/developers/useful_commands.md.txt new file mode 100644 index 00000000..08c5a2a0 --- /dev/null +++ b/_sources/user_profiles/developers/useful_commands.md.txt @@ -0,0 +1,115 @@ +# Useful Commands for Development + +In the [developer tutorial](https://sandialabs.github.io/spack-manager/user_profiles/developers/developer_tutorial.html) the granular Spack commands are shown to help youe become familiar with the process of building with Spack. +Using these commands (along with familiarization with the [spack.yaml](https://spack.readthedocs.io/en/latest/environments.html#spack-yaml)) will allow you to create a fully customized build environments. + +In practice many of these commands are redundant and unneccesary for standard development workflows. +To assist with your workflow we've pre-scripted these commands in a set of _quick-commands_. +These commands are available in your shell once you've sourced `$SPACK_MANAGER/scripts/quick_commands.sh`, and provide a drop off point in the workflows based on your needs. +All of the _quick-commands_ will echo all the calls to spack (pre-pended with a `+ ` ) so you can see what is being called and can reproduce them execution outside these scripts as needed. + +Information on these commands are provided below. + +For a quick reference: the commands that are anticipated to be the most commonly used are: +- [`quick-develop`](#quick-develop) +- [`quick-activate`](#quick-activate) +- [`build-env-dive`](#build-env-dive) + +## Environment setup process +As a reminder, the complete, granular list of steps to setup an environment after sourcing `$SPACK_MANAGER/start.sh` are: +1. `spack manager create-env`: create an environment +2. `spack env activate`: activate the environment you created +3. `spack add`: add root specs to the environment +4. `spack manager develop`: setup the source code you want to edit and configure the environment to use that code +5. `spack manager external`: optional step to link your environment against pre-built binaries +6. `spack concretize`: solve the dependency graph for your environment +7. `spack install`: build the software + +## Environment loading process +The complete, granular list of steps to re-use an environment after sourcing `$SPACK_MANAGER/start.sh` are: +1. `spack env activate`: activate an environment +2. `spack build env [package] [commands]` or `spack cd -b [spec] && bash -rcfile ../spack-build-env.txt`: run a command in the build environment or dive into the build environment in a subshell + +## Environment setup commands +The following commands are the convenience functions for setting up a development environment. +All of these commands will exit the shell with an active Spack environment whose name will be added +to your shell prompt. +Please note that these commands are principally constructing a valid `spack.yaml` file for you in your environment, +and that file can be manipulated as needed after the commands are executed. + +(#quick-create)= +### quick-create +`quick-create` executes the [environment setup process](#environment-setup-process) and exits at step 4. +If you supply specs with the `--spec` or `-s` flag then those will be added as root specs and you can effectively be at step 5 +`spack manager develop`. + +***When should I use `quick-create`?*** +This command should be used by individuals who want to have control over the git clone process and/or locations of the source code +they are intending to develop. +`spack manager develop` gives you the abiilty to point to pre-cloned code, or to select the fork and branch you want to clone from. +If these are desirable features then you will need to run the remaining steps of the [environment setup process](#environment-setup-process) +manually. + +(#quick-create-dev)= +### quick-create-dev +`quick-create-dev` executes the [environment setup process](#environment-setup-process) and exits at step 5. +If you supply concrete specs, which means they have the name and version (i.e. `amr-wind@main`), then `spack-manager develop` will be called for you +and the default repos/branches will be cloned to the environment directory for you. +If you fail to supply a concrete spec then this command will give a warning letting you know the spec wasn't concrete, and the behavior will stop at step 4. +In other words it will behave exactly like [`quick-create`](#quick-create). + +***When should I use `quick-create-dev`?*** +`quick-create-dev` should be used if you don't mind accepting the default repo cloning, but need to specifiy the externals you will link against +with `spack manager external` or if you don't want to use externals at all. +A common scenario for this is if you are building with the non-standard view that you can see from `spack manager external --list`. +The first view listed in the parenthesis for the latest timestamped snapshot is the default. +If this one doesn't match your build needs then you will need to specifiy the correct one manually. + +(#quick-develop)= +### quick-develop +`quick-develop` executes the [environment setup process](#environment-setup-process) and exits at step 7. +This command is intended to execute the entire setup process for the default development environment on a given machine. +Upon successful execution all that is required after this command is to run `spack install` since `spack install` will also perform +concretization. +The same requirement for valid concrete specs that was in [`quick-create-dev`](#quick-create-dev) applies here along with all the same constraints. + +***When should I use `quick-develop`?*** +`quick-develop` should be used if you want a rapid development environment without any need for customization. +This is the fastest and least number of commands to get you started and should work for standard development needs. + +## Environment re-use commands +These commands are designed to help you efficiently re-use an environment that has already been setup. + +(#quick-activate)= +### quick-activate +`quick-activate` executes the first two steps of the [environment loading process](#environment-loading-process) +i.e. `spack-start && spack env activate`. +To use it you simply pass the directory path to the environment you wish to activate i.e. `quick-activate $SPACK_MANAGER/environments/exawind` +and it will activate the environment and add the name of the environment to your shell prompt. + +***When should I use `quick-activate`?*** +Whenever you want to come back to an environment in a new shell. +There are really no down-sides to this command unless you don't like the environment name being added to your prompt. + +(#build-env-dive)= +### build-env-dive +`build-env-dive` takes a spec as an argument and will move you to the location of the build directory for that spec and launch a sub-shell using the spec's build environment. +This command allows developers to work as if they had built the software manually outside of spack. +You can call `make`, `make clean`, `make install`, `ctest` etc. +Simply type `exit` to return to your original shell where you called `build-env-dive`. +It should be cautioned that diving into this environment can do things like change the version of git/python in your shell. +Also if you are doing a multi-compnent simply calling `make` will not update the entire stack like `spack install` will. + +***When should I use `build-env-dive`?*** +This command is most effective when you are just iterating on one software component and need to keep executing commands in that environment. +For a one off like checking a test `spack build-env [spec] [command]` is probably more efficient, but it is also clunkier to use. +In general `build-env-dive` command should be used freely as long as you are okay with it moving you to directories and are aware of the +potential issues related to opening a sub-shell with potentially different configurations. +In practice this has not been much of an issue. + +## Other Commands + +(#remove-spack-prompt)= +### remove-spack-prompt +This command takes no arguments unless you pass `-h` or `--help`. +It simply removes the prompt with the environment name that the _quick-commands_ add. diff --git a/_sources/user_profiles/system_admins/creating_a_project.md.txt b/_sources/user_profiles/system_admins/creating_a_project.md.txt new file mode 100644 index 00000000..e4779aae --- /dev/null +++ b/_sources/user_profiles/system_admins/creating_a_project.md.txt @@ -0,0 +1,290 @@ +# Creating and configuring a Spack-Manager Project + +Spack-Manager projects are the method for organizing configuration files and package repositories +associated with a given software application. + +If a pre-configred project exists then it simply has to be add to the Spack-Manager configuration file. +This section will demonstrate the process of setting up a Spack-Manager project from scratch using the +[ExaWind application](https://github.com/Exawind/). +This is just an example that is not going to be kept up-to-date for Exawind since it is a living, independent project. +The actual ExaWind configuration can be found [here](https://github.com/Exawind/exawind-manager/). + +## Creating a Project from Scratch + +A Project is really just a collection of directories and couple of optional python files. +In the `spack-manager.yaml` configuration file paths are provided to the projects that this instance of +Spack-Manager is supporting. + +``` console +$ cat spack-manager/spack-manager.yaml + +spack-manager: + projects: + - $SCRATCH/exawind-demo + +$ ls -lh $SCRATCH/exawind-demo +ls: /Users/psakiev/scratch/exawind-demo: No such file or directory +``` + +If a non-existent path is added to the `Projects` list in the `spack-manager/spack-manager.yaml` file +then these initial directories will automatically be created the first time a `spack manager` command is run. +It should also be noted that the autocompletion of variables inside these paths (such as the `$SCRATCH` environment +variable in this example, follow the same [variable conventions](https://spack.readthedocs.io/en/latest/configuration.html#config-file-variables) utilized by Spack. +This is because Spack-Manager is importing and using the Spack code for these operations. + +``` console +$ spack manager find-machine --list +Project: Machine: Detected: (+/-) +------------------------------------------------------------ + +$ tree $SCRATCH/exawind-demo +/Users/psakiev/scratch/exawind-demo +├── configs +└── repos + +3 directories, 0 files +``` + +Once the first `spack manager` command is run the project `configs` and `repos` directories get populated. +The `configs` directory is where machine specific spack configuration files are stored. +Since this directory is currently empty no machines show up when `spack manager find-machine --list` is run. +The next step is to add some machines and configuration files. +Note that __machines__ is a loose term, and it is really a bifurcation of configurations. +The term __machine__ was selected since application projects typically have to tweak their spack configurations +on each new machine/platform. + +## Populating Machine Specific Configurations +Directories within the project's `configs` directory will be delineated by their names. +Let's add a directory named `darwin` inside the `configs` directory and re-run `spack manager find-machine --list`. + +``` console +$ mkdir $SCRATCH/exawind-demo/configs/darwin +$ spack manager find-machine --list +Project: Machine: Detected: (+/-) +------------------------------------------------------------ +exawind-demo darwin - +``` + +`darwin` is automatically picked up as an available machine by the `find-machine` command, and any configuration files that +are added inside this directory will be added to an environment created with a `darwin` machine specified. +It should also be noted that the project name `exawind-demo` comes from the name of the parent directory. +Now configurations can be added. +The following two configurations are used by ExaWind. + +``` yaml +# config.yaml +config: + mirrors: + e4s: https://cache.e4s.io +``` + +``` yaml +# packages.yaml +packages: + hypre: + variants: +shared~fortran + all: + compiler: [apple-clang, gcc, clang] + providers: + mpi: [mpich, openmpi] +``` + +### Anonymous Machines +There are two anonymous machines that are reserved for project and users to utilize: `base` and `user`. +The `configs/base` directory is designed to hold project wide configurations that are the defaults utilized by every environment. +For example, the software project has non-default package variants they wish to use uniformly across all platforms these could +be set in the `configs/base/packages.yaml` file. + +The `configs/users` directory is one that allows users to set their own personal preferences or make tweaks before pushing them +to the whole team. An example here is if one user really prefers a specific flavor of MPI and the software project is not constrained +then they could configure that in the `configs/user/packages.yaml` file. + +The hierarchy of precedent for these configs are: +1. `user` +2. `machine` +3. `base` +where the smaller number means higher precedent. + +So any configurations in `base` are not the law and can be overridden on each machine as necessary. +An example of this would be if the project prefers to build with `+shared` but on specific platform can only support `~shared`. +As a reminder, this hierarchy is only for creating the default environment configuration on each platform when it is created. +These are added to the `spack.yaml` via entries in the `includes` [list](https://spack.readthedocs.io/en/latest/environments.html#included-configurations). +Each environment can still be customized by modifying the `spack.yaml` file and using [additional configuration techniques](https://spack.readthedocs.io/en/latest/environments.html#configuring-environments). + +For completeness, the optional `base` and `user` directories will now be added to the `exawind-demo` project. + +``` console +$ mkdir $SCRATCH/exawind-demo/configs/base +$ mkdir $SCRATCH/exawind-demo/configs/user +$ spack manager find-machine --list +Project: Machine: Detected: (+/-) +------------------------------------------------------------ +exawind-demo darwin - +``` + +The output above shows how these config directories are ignored by the `find-maachine` command. +Next we'll add some of the `base` configs used by ExaWind to the `base` directory. + +``` yaml +# config.yaml +config: + source_cache: ~/.spack_downloads + misc_cache: $spack/../.cache + build_stage: + - $spack/../stage + concretizer: clingo +``` + +``` yaml +# concretizer.yaml +concretizer: + unify: false + reuse: false +``` + +Now if we create an environment using `spack manager create-env --machine darwin` we will see all the configs that have been added in the `include.yaml` file. + +``` console +$ spack manager create-env --machine darwin -d $SCRATCH/example-env +making /Users/psakiev/scratch/example-env + +$ cat $SCRATCH/example-env/spack.yaml +# This is a Spack Environment file. +# +# It describes a set of packages to be installed, along with +# configuration settings. +spack: + # add package specs to the `specs` list + specs: [] + view: false + concretizer: + unify: true + include: + - include.yaml + +$ cat $SCRATCH/example-env/include.yaml +concretizer: + unify: false + reuse: false +packages: + hypre: + variants: +shared~fortran + all: + compiler: [apple-clang, gcc, clang] + providers: + mpi: [mpich, openmpi] +config: + mirrors: + e4s: https://cache.e4s.io + source_cache: ~/.spack_downloads + misc_cache: $spack/../.cache + build_stage: + - $spack/../stage + concretizer: clingo +``` + +## Configuring Machine Auto-detection + +The last column from the output of `spack manager find-machine --list` indicates if the configuration +was detected for the current machine. +The default behavior is to detect nothing and require users to specify the machine they want to use. +However, setting up automatic detection is simple and highly configurable for each project and each machine. + +To add detection a project must have a python file named `find-[project].py` in the top-level directory of the project (`exawind-demo` in this example). +`find-[project].py` needs to have a method named `detector` that takes a string with the machine name and returns +`True` or `False` depending on if the current machine meets the criteria for that name. + +Here is an example `find-exawind-demo.py` script + +``` python +import sys + +def detector(name): + """ + A function that will check if the supplied name/machine + matches a known machine configuration + """ + # dictionary that is easily extensible where key is the name we want to match + # and the value is function that can be evaluated to test the actual system we + # are one + known_machines = { + "darwin": lambda: sys.platform == "darwin", + } + + if name in known_machines: + return known_machines[name]() + else: + return False + +``` + +Now when the `find-machine` command is run the `darwin` machine will be detected. +``` console +$ spack manager find-machine --list +Project: Machine: Detected: (+/-) +------------------------------------------------------------ +exawind-demo darwin + +``` + +Users are free to implement and sort of detection script they want. +The only requirements are that the method `detector` have a positional +argument for the name of the machine to check for, and returns a boolean to indicate if that supplied name +was detected. + +## Setting up Spack Package Repositories +The `[Project]/repos` directory is a place holder for package repositories that are paired with the softwware applications development/deployment. +The simplest way to ensure the appropriate repos are included is to add a reference to them in +`[Project]/configs/base/repos.yaml` file. +This is a way to ensure that any environment created with Spack-Manager for the desired project will include the repos. + +An example for ExaWind is as follows: +``` yaml +# repos.yaml +repos: + - $spack/../repos/exawind +``` + +Where the `$spack` is a supported +[configuration variable](https://spack.readthedocs.io/en/latest/configuration.html#config-file-variables) +that will be expanded by spack. +This works for ExaWind because ExaWind creates a fixed mirror of spack that is submoduled +into their Project repository. + +Utilizing a configuration variable, environment variable, or manually updating the repo paths are currently +the only way to point to repos in arbitrary locations on the filesystem. +Users may also add the `copy_repos: true` flag to their projects inside the `spack-manager.yaml` configuration +file if they wish to just automatically copy the repo files locally to an environment when it is created. + +``` yaml +spack-manager: + projects: + - $SCRATCH/exawind-demo + copy_repos: true +``` + +In this case the repo specification would be properly resolved with the following `repo.yaml` file in the `base` configs. + +``` yaml +# repos.yaml +repos: + - $env/repos/exawind +``` + +Now when an environment is created the `[Projects]/repos` directory will be copied completely to the environment, and +the environment will look for the copy relative to its own location. + +Please note, that these are mainly small tricks to utilize spack's builtin path resolution strategies. +Additional work in the future is anticipated to make this a more seamless setup and transition. + +## Adding Version Control +At this point the `exawind-demo` project is populated with an initial set of configurations. +It is highly suggested that it be placed under some form of version control. +`git` is by far the most popular tool for version control at the moment. +A suggested `.gitignore` file would look something like the following: +``` bash +# basic python files +__pycache__ +*pyc +# some operations in spack-manager can currently create this directory +.tmp +``` diff --git a/_sources/user_profiles/system_admins/system_admins.rst.txt b/_sources/user_profiles/system_admins/system_admins.rst.txt new file mode 100644 index 00000000..dbbd4c3f --- /dev/null +++ b/_sources/user_profiles/system_admins/system_admins.rst.txt @@ -0,0 +1,11 @@ +System Administrator Documentation +================================== + +This section of documentation is for users who will be using Spack-Manager to manage +the software development process for software developers and/or end users on specific machines. + +.. toctree:: + :glob: + :maxdepth: 2 + + creating_a_project diff --git a/_sources/user_profiles/user_profiles.rst.txt b/_sources/user_profiles/user_profiles.rst.txt new file mode 100644 index 00000000..dce57eed --- /dev/null +++ b/_sources/user_profiles/user_profiles.rst.txt @@ -0,0 +1,10 @@ +User Profiles +============= + +.. toctree:: + :glob: + :maxdepth: 2 + + analysts/analysts + developers/developers.rst + system_admins/system_admins.rst diff --git a/_static/_sphinx_javascript_frameworks_compat.js b/_static/_sphinx_javascript_frameworks_compat.js new file mode 100644 index 00000000..81415803 --- /dev/null +++ b/_static/_sphinx_javascript_frameworks_compat.js @@ -0,0 +1,123 @@ +/* Compatability shim for jQuery and underscores.js. + * + * Copyright Sphinx contributors + * Released under the two clause BSD licence + */ + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} diff --git a/_static/basic.css b/_static/basic.css new file mode 100644 index 00000000..7ebbd6d0 --- /dev/null +++ b/_static/basic.css @@ -0,0 +1,914 @@ +/* + * Sphinx stylesheet -- basic theme. + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin-top: 10px; +} + +ul.search li { + padding: 5px 0; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/_static/css/badge_only.css b/_static/css/badge_only.css new file mode 100644 index 00000000..88ba55b9 --- /dev/null +++ b/_static/css/badge_only.css @@ -0,0 +1 @@ +.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px} \ No newline at end of file diff --git a/_static/css/fonts/Roboto-Slab-Bold.woff b/_static/css/fonts/Roboto-Slab-Bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Bold.woff differ diff --git a/_static/css/fonts/Roboto-Slab-Bold.woff2 b/_static/css/fonts/Roboto-Slab-Bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Bold.woff2 differ diff --git a/_static/css/fonts/Roboto-Slab-Regular.woff b/_static/css/fonts/Roboto-Slab-Regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Regular.woff differ diff --git a/_static/css/fonts/Roboto-Slab-Regular.woff2 b/_static/css/fonts/Roboto-Slab-Regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Regular.woff2 differ diff --git a/_static/css/fonts/fontawesome-webfont.eot b/_static/css/fonts/fontawesome-webfont.eot new file mode 100644 index 00000000..e9f60ca9 Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.eot differ diff --git a/_static/css/fonts/fontawesome-webfont.svg b/_static/css/fonts/fontawesome-webfont.svg new file mode 100644 index 00000000..855c845e --- /dev/null +++ b/_static/css/fonts/fontawesome-webfont.svg @@ -0,0 +1,2671 @@ + + + + +Created by FontForge 20120731 at Mon Oct 24 17:37:40 2016 + By ,,, +Copyright Dave Gandy 2016. All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/_static/css/fonts/fontawesome-webfont.ttf b/_static/css/fonts/fontawesome-webfont.ttf new file mode 100644 index 00000000..35acda2f Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.ttf differ diff --git a/_static/css/fonts/fontawesome-webfont.woff b/_static/css/fonts/fontawesome-webfont.woff new file mode 100644 index 00000000..400014a4 Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.woff differ diff --git a/_static/css/fonts/fontawesome-webfont.woff2 b/_static/css/fonts/fontawesome-webfont.woff2 new file mode 100644 index 00000000..4d13fc60 Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.woff2 differ diff --git a/_static/css/fonts/lato-bold-italic.woff b/_static/css/fonts/lato-bold-italic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/_static/css/fonts/lato-bold-italic.woff differ diff --git a/_static/css/fonts/lato-bold-italic.woff2 b/_static/css/fonts/lato-bold-italic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/_static/css/fonts/lato-bold-italic.woff2 differ diff --git a/_static/css/fonts/lato-bold.woff b/_static/css/fonts/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/_static/css/fonts/lato-bold.woff differ diff --git a/_static/css/fonts/lato-bold.woff2 b/_static/css/fonts/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/_static/css/fonts/lato-bold.woff2 differ diff --git a/_static/css/fonts/lato-normal-italic.woff b/_static/css/fonts/lato-normal-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/_static/css/fonts/lato-normal-italic.woff differ diff --git a/_static/css/fonts/lato-normal-italic.woff2 b/_static/css/fonts/lato-normal-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/_static/css/fonts/lato-normal-italic.woff2 differ diff --git a/_static/css/fonts/lato-normal.woff b/_static/css/fonts/lato-normal.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/_static/css/fonts/lato-normal.woff differ diff --git a/_static/css/fonts/lato-normal.woff2 b/_static/css/fonts/lato-normal.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/_static/css/fonts/lato-normal.woff2 differ diff --git a/_static/css/theme.css b/_static/css/theme.css new file mode 100644 index 00000000..0f14f106 --- /dev/null +++ b/_static/css/theme.css @@ -0,0 +1,4 @@ +html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*! + * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome + * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License) + */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a button.pull-right.toctree-expand,.wy-menu-vertical li.on a button.pull-right.toctree-expand,.wy-menu-vertical li button.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li button.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content .eqno .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content .eqno a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content p a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li a button.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content .eqno .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content p .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li button.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content .eqno .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a button.toctree-expand,.btn .wy-menu-vertical li.on a button.toctree-expand,.btn .wy-menu-vertical li button.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content .eqno .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a button.toctree-expand,.nav .wy-menu-vertical li.on a button.toctree-expand,.nav .wy-menu-vertical li button.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .eqno .btn .headerlink,.rst-content .eqno .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p .btn .headerlink,.rst-content p .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn button.toctree-expand,.wy-menu-vertical li.current>a .btn button.toctree-expand,.wy-menu-vertical li.current>a .nav button.toctree-expand,.wy-menu-vertical li .nav button.toctree-expand,.wy-menu-vertical li.on a .btn button.toctree-expand,.wy-menu-vertical li.on a .nav button.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .eqno .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li button.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .eqno .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li button.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .eqno .btn .fa-large.headerlink,.rst-content .eqno .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p .btn .fa-large.headerlink,.rst-content p .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn button.fa-large.toctree-expand,.wy-menu-vertical li .nav button.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .eqno .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li button.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .eqno .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li button.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .eqno .btn .fa-spin.headerlink,.rst-content .eqno .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p .btn .fa-spin.headerlink,.rst-content p .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn button.fa-spin.toctree-expand,.wy-menu-vertical li .nav button.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content .eqno .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li button.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content .eqno .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li button.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content .eqno .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li button.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content .eqno .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini button.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.rst-content section ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.rst-content section ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.rst-content section ul li p:last-child,.rst-content section ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.rst-content section ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.rst-content section ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.rst-content section ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content .section ol.arabic,.rst-content .toctree-wrapper ol,.rst-content .toctree-wrapper ol.arabic,.rst-content section ol,.rst-content section ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol.arabic li,.rst-content .section ol li,.rst-content .toctree-wrapper ol.arabic li,.rst-content .toctree-wrapper ol li,.rst-content section ol.arabic li,.rst-content section ol li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol.arabic li ul,.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content .toctree-wrapper ol.arabic li ul,.rst-content .toctree-wrapper ol li p:last-child,.rst-content .toctree-wrapper ol li ul,.rst-content section ol.arabic li ul,.rst-content section ol li p:last-child,.rst-content section ol li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol.arabic li ul li,.rst-content .section ol li ul li,.rst-content .toctree-wrapper ol.arabic li ul li,.rst-content .toctree-wrapper ol li ul li,.rst-content section ol.arabic li ul li,.rst-content section ol li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs>li{display:inline-block;padding-top:5px}.wy-breadcrumbs>li.wy-breadcrumbs-aside{float:right}.rst-content .wy-breadcrumbs>li code,.rst-content .wy-breadcrumbs>li tt,.wy-breadcrumbs>li .rst-content tt,.wy-breadcrumbs>li code{all:inherit;color:inherit}.breadcrumb-item:before{content:"/";color:#bbb;font-size:13px;padding:0 6px 0 3px}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li button.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d;border:none;background:none;padding:0}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover button.toctree-expand,.wy-menu-vertical li.on a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover button.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover button.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 button.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 button.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover button.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active button.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em;max-width:100%}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search .wy-dropdown>aactive,.wy-side-nav-search .wy-dropdown>afocus,.wy-side-nav-search>a:hover,.wy-side-nav-search>aactive,.wy-side-nav-search>afocus{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon,.wy-side-nav-search>a.icon{display:block}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.switch-menus{position:relative;display:block;margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-side-nav-search>div.switch-menus>div.language-switch,.wy-side-nav-search>div.switch-menus>div.version-switch{display:inline-block;padding:.2em}.wy-side-nav-search>div.switch-menus>div.language-switch select,.wy-side-nav-search>div.switch-menus>div.version-switch select{display:inline-block;margin-right:-2rem;padding-right:2rem;max-width:240px;text-align-last:center;background:none;border:none;border-radius:0;box-shadow:none;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-size:1em;font-weight:400;color:hsla(0,0%,100%,.3);cursor:pointer;appearance:none;-webkit-appearance:none;-moz-appearance:none}.wy-side-nav-search>div.switch-menus>div.language-switch select:active,.wy-side-nav-search>div.switch-menus>div.language-switch select:focus,.wy-side-nav-search>div.switch-menus>div.language-switch select:hover,.wy-side-nav-search>div.switch-menus>div.version-switch select:active,.wy-side-nav-search>div.switch-menus>div.version-switch select:focus,.wy-side-nav-search>div.switch-menus>div.version-switch select:hover{background:hsla(0,0%,100%,.1);color:hsla(0,0%,100%,.5)}.wy-side-nav-search>div.switch-menus>div.language-switch select option,.wy-side-nav-search>div.switch-menus>div.version-switch select option{color:#000}.wy-side-nav-search>div.switch-menus>div.language-switch:has(>select):after,.wy-side-nav-search>div.switch-menus>div.version-switch:has(>select):after{display:inline-block;width:1.5em;height:100%;padding:.1em;content:"\f0d7";font-size:1em;line-height:1.2em;font-family:FontAwesome;text-align:center;pointer-events:none;box-sizing:border-box}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .eqno .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content .eqno .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li button.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version button.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}.rst-content .toctree-wrapper>p.caption,.rst-content h1,.rst-content h2,.rst-content h3,.rst-content h4,.rst-content h5,.rst-content h6{margin-bottom:24px}.rst-content img{max-width:100%;height:auto}.rst-content div.figure,.rst-content figure{margin-bottom:24px}.rst-content div.figure .caption-text,.rst-content figure .caption-text{font-style:italic}.rst-content div.figure p:last-child.caption,.rst-content figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center,.rst-content figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img,.rst-content section>a>img,.rst-content section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp,.rst-content div.highlight span.linenos{user-select:none;pointer-events:none}.rst-content div.highlight span.linenos{display:inline-block;padding-left:0;padding-right:12px;margin-right:12px;border-right:1px solid #e6e9ea}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li,.rst-content .toctree-wrapper ol.loweralpha,.rst-content .toctree-wrapper ol.loweralpha>li,.rst-content section ol.loweralpha,.rst-content section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li,.rst-content .toctree-wrapper ol.upperalpha,.rst-content .toctree-wrapper ol.upperalpha>li,.rst-content section ol.upperalpha,.rst-content section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*,.rst-content .toctree-wrapper ol li>*,.rst-content .toctree-wrapper ul li>*,.rst-content section ol li>*,.rst-content section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child,.rst-content .toctree-wrapper ol li>:first-child,.rst-content .toctree-wrapper ul li>:first-child,.rst-content section ol li>:first-child,.rst-content section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child,.rst-content .toctree-wrapper ol li>p,.rst-content .toctree-wrapper ol li>p:last-child,.rst-content .toctree-wrapper ul li>p,.rst-content .toctree-wrapper ul li>p:last-child,.rst-content section ol li>p,.rst-content section ol li>p:last-child,.rst-content section ul li>p,.rst-content section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child,.rst-content .toctree-wrapper ol li>p:only-child,.rst-content .toctree-wrapper ol li>p:only-child:last-child,.rst-content .toctree-wrapper ul li>p:only-child,.rst-content .toctree-wrapper ul li>p:only-child:last-child,.rst-content section ol li>p:only-child,.rst-content section ol li>p:only-child:last-child,.rst-content section ul li>p:only-child,.rst-content section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul,.rst-content .toctree-wrapper ol li>ol,.rst-content .toctree-wrapper ol li>ul,.rst-content .toctree-wrapper ul li>ol,.rst-content .toctree-wrapper ul li>ul,.rst-content section ol li>ol,.rst-content section ol li>ul,.rst-content section ul li>ol,.rst-content section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul,.rst-content .toctree-wrapper ol.simple li>*,.rst-content .toctree-wrapper ol.simple li ol,.rst-content .toctree-wrapper ol.simple li ul,.rst-content .toctree-wrapper ul.simple li>*,.rst-content .toctree-wrapper ul.simple li ol,.rst-content .toctree-wrapper ul.simple li ul,.rst-content section ol.simple li>*,.rst-content section ol.simple li ol,.rst-content section ol.simple li ul,.rst-content section ul.simple li>*,.rst-content section ul.simple li ol,.rst-content section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink{opacity:0;font-size:14px;font-family:FontAwesome;margin-left:.5em}.rst-content .code-block-caption .headerlink:focus,.rst-content .code-block-caption:hover .headerlink,.rst-content .eqno .headerlink:focus,.rst-content .eqno:hover .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink:focus,.rst-content .toctree-wrapper>p.caption:hover .headerlink,.rst-content dl dt .headerlink:focus,.rst-content dl dt:hover .headerlink,.rst-content h1 .headerlink:focus,.rst-content h1:hover .headerlink,.rst-content h2 .headerlink:focus,.rst-content h2:hover .headerlink,.rst-content h3 .headerlink:focus,.rst-content h3:hover .headerlink,.rst-content h4 .headerlink:focus,.rst-content h4:hover .headerlink,.rst-content h5 .headerlink:focus,.rst-content h5:hover .headerlink,.rst-content h6 .headerlink:focus,.rst-content h6:hover .headerlink,.rst-content p.caption .headerlink:focus,.rst-content p.caption:hover .headerlink,.rst-content p .headerlink:focus,.rst-content p:hover .headerlink,.rst-content table>caption .headerlink:focus,.rst-content table>caption:hover .headerlink{opacity:1}.rst-content p a{overflow-wrap:anywhere}.rst-content .wy-table td p,.rst-content .wy-table td ul,.rst-content .wy-table th p,.rst-content .wy-table th ul,.rst-content table.docutils td p,.rst-content table.docutils td ul,.rst-content table.docutils th p,.rst-content table.docutils th ul,.rst-content table.field-list td p,.rst-content table.field-list td ul,.rst-content table.field-list th p,.rst-content table.field-list th ul{font-size:inherit}.rst-content .btn:focus{outline:2px solid}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .citation-reference>span.fn-bracket,.rst-content .footnote-reference>span.fn-bracket{display:none}.rst-content .hlist{width:100%}.rst-content dl dt span.classifier:before{content:" : "}.rst-content dl dt span.classifier-delimiter{display:none!important}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:auto minmax(80%,95%)}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{display:inline-grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{display:grid;grid-template-columns:auto auto minmax(.65rem,auto) minmax(40%,95%)}html.writer-html5 .rst-content aside.citation>span.label,html.writer-html5 .rst-content aside.footnote>span.label,html.writer-html5 .rst-content div.citation>span.label{grid-column-start:1;grid-column-end:2}html.writer-html5 .rst-content aside.citation>span.backrefs,html.writer-html5 .rst-content aside.footnote>span.backrefs,html.writer-html5 .rst-content div.citation>span.backrefs{grid-column-start:2;grid-column-end:3;grid-row-start:1;grid-row-end:3}html.writer-html5 .rst-content aside.citation>p,html.writer-html5 .rst-content aside.footnote>p,html.writer-html5 .rst-content div.citation>p{grid-column-start:4;grid-column-end:5}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{margin-bottom:24px}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.citation>dt,html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.citation>dt>span.brackets:before,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.citation>dt>span.brackets:after,html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a{word-break:keep-all}html.writer-html5 .rst-content dl.citation>dt>span.fn-backref>a:not(:first-child):before,html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content dl.citation>dd,html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.citation>dd p,html.writer-html5 .rst-content dl.footnote>dd p{font-size:.9rem}html.writer-html5 .rst-content aside.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content div.citation{padding-left:1rem;padding-right:1rem;font-size:.9rem;line-height:1.2rem}html.writer-html5 .rst-content aside.citation p,html.writer-html5 .rst-content aside.footnote p,html.writer-html5 .rst-content div.citation p{font-size:.9rem;line-height:1.2rem;margin-bottom:12px}html.writer-html5 .rst-content aside.citation span.backrefs,html.writer-html5 .rst-content aside.footnote span.backrefs,html.writer-html5 .rst-content div.citation span.backrefs{text-align:left;font-style:italic;margin-left:.65rem;word-break:break-word;word-spacing:-.1rem;max-width:5rem}html.writer-html5 .rst-content aside.citation span.backrefs>a,html.writer-html5 .rst-content aside.footnote span.backrefs>a,html.writer-html5 .rst-content div.citation span.backrefs>a{word-break:keep-all}html.writer-html5 .rst-content aside.citation span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content aside.footnote span.backrefs>a:not(:first-child):before,html.writer-html5 .rst-content div.citation span.backrefs>a:not(:first-child):before{content:" "}html.writer-html5 .rst-content aside.citation span.label,html.writer-html5 .rst-content aside.footnote span.label,html.writer-html5 .rst-content div.citation span.label{line-height:1.2rem}html.writer-html5 .rst-content aside.citation-list,html.writer-html5 .rst-content aside.footnote-list,html.writer-html5 .rst-content div.citation-list{margin-bottom:24px}html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content aside.footnote,html.writer-html5 .rst-content aside.footnote-list aside.footnote,html.writer-html5 .rst-content div.citation-list>div.citation,html.writer-html5 .rst-content dl.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content aside.footnote-list aside.footnote code,html.writer-html5 .rst-content aside.footnote-list aside.footnote tt,html.writer-html5 .rst-content aside.footnote code,html.writer-html5 .rst-content aside.footnote tt,html.writer-html5 .rst-content div.citation-list>div.citation code,html.writer-html5 .rst-content div.citation-list>div.citation tt,html.writer-html5 .rst-content dl.citation code,html.writer-html5 .rst-content dl.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040;overflow-wrap:normal}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}.rst-content dl dd>ol:last-child,.rst-content dl dd>p:last-child,.rst-content dl dd>table:last-child,.rst-content dl dd>ul:last-child{margin-bottom:0}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px;max-width:100%}html.writer-html4 .rst-content dl:not(.docutils) .k,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .k{font-style:italic}html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) .sig-name{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#000}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel,.rst-content .menuselection{font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content .guilabel,.rst-content .menuselection{border:1px solid #7fbbe3;background:#e7f2fa}.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>.kbd,.rst-content :not(dl.option-list)>:not(dt):not(kbd):not(.kbd)>kbd{color:inherit;font-size:80%;background-color:#fff;border:1px solid #a6a6a6;border-radius:4px;box-shadow:0 2px grey;padding:2.4px 6px;margin:auto 0}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block} \ No newline at end of file diff --git a/_static/doctools.js b/_static/doctools.js new file mode 100644 index 00000000..0398ebb9 --- /dev/null +++ b/_static/doctools.js @@ -0,0 +1,149 @@ +/* + * Base JavaScript utilities for all Sphinx HTML documentation. + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/_static/documentation_options.js b/_static/documentation_options.js new file mode 100644 index 00000000..e21c068c --- /dev/null +++ b/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '0.1', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/_static/file.png b/_static/file.png new file mode 100644 index 00000000..a858a410 Binary files /dev/null and b/_static/file.png differ diff --git a/_static/fonts/Lato/lato-bold.eot b/_static/fonts/Lato/lato-bold.eot new file mode 100644 index 00000000..3361183a Binary files /dev/null and b/_static/fonts/Lato/lato-bold.eot differ diff --git a/_static/fonts/Lato/lato-bold.ttf b/_static/fonts/Lato/lato-bold.ttf new file mode 100644 index 00000000..29f691d5 Binary files /dev/null and b/_static/fonts/Lato/lato-bold.ttf differ diff --git a/_static/fonts/Lato/lato-bold.woff b/_static/fonts/Lato/lato-bold.woff new file mode 100644 index 00000000..c6dff51f Binary files /dev/null and b/_static/fonts/Lato/lato-bold.woff differ diff --git a/_static/fonts/Lato/lato-bold.woff2 b/_static/fonts/Lato/lato-bold.woff2 new file mode 100644 index 00000000..bb195043 Binary files /dev/null and b/_static/fonts/Lato/lato-bold.woff2 differ diff --git a/_static/fonts/Lato/lato-bolditalic.eot b/_static/fonts/Lato/lato-bolditalic.eot new file mode 100644 index 00000000..3d415493 Binary files /dev/null and b/_static/fonts/Lato/lato-bolditalic.eot differ diff --git a/_static/fonts/Lato/lato-bolditalic.ttf b/_static/fonts/Lato/lato-bolditalic.ttf new file mode 100644 index 00000000..f402040b Binary files /dev/null and b/_static/fonts/Lato/lato-bolditalic.ttf differ diff --git a/_static/fonts/Lato/lato-bolditalic.woff b/_static/fonts/Lato/lato-bolditalic.woff new file mode 100644 index 00000000..88ad05b9 Binary files /dev/null and b/_static/fonts/Lato/lato-bolditalic.woff differ diff --git a/_static/fonts/Lato/lato-bolditalic.woff2 b/_static/fonts/Lato/lato-bolditalic.woff2 new file mode 100644 index 00000000..c4e3d804 Binary files /dev/null and b/_static/fonts/Lato/lato-bolditalic.woff2 differ diff --git a/_static/fonts/Lato/lato-italic.eot b/_static/fonts/Lato/lato-italic.eot new file mode 100644 index 00000000..3f826421 Binary files /dev/null and b/_static/fonts/Lato/lato-italic.eot differ diff --git a/_static/fonts/Lato/lato-italic.ttf b/_static/fonts/Lato/lato-italic.ttf new file mode 100644 index 00000000..b4bfc9b2 Binary files /dev/null and b/_static/fonts/Lato/lato-italic.ttf differ diff --git a/_static/fonts/Lato/lato-italic.woff b/_static/fonts/Lato/lato-italic.woff new file mode 100644 index 00000000..76114bc0 Binary files /dev/null and b/_static/fonts/Lato/lato-italic.woff differ diff --git a/_static/fonts/Lato/lato-italic.woff2 b/_static/fonts/Lato/lato-italic.woff2 new file mode 100644 index 00000000..3404f37e Binary files /dev/null and b/_static/fonts/Lato/lato-italic.woff2 differ diff --git a/_static/fonts/Lato/lato-regular.eot b/_static/fonts/Lato/lato-regular.eot new file mode 100644 index 00000000..11e3f2a5 Binary files /dev/null and b/_static/fonts/Lato/lato-regular.eot differ diff --git a/_static/fonts/Lato/lato-regular.ttf b/_static/fonts/Lato/lato-regular.ttf new file mode 100644 index 00000000..74decd9e Binary files /dev/null and b/_static/fonts/Lato/lato-regular.ttf differ diff --git a/_static/fonts/Lato/lato-regular.woff b/_static/fonts/Lato/lato-regular.woff new file mode 100644 index 00000000..ae1307ff Binary files /dev/null and b/_static/fonts/Lato/lato-regular.woff differ diff --git a/_static/fonts/Lato/lato-regular.woff2 b/_static/fonts/Lato/lato-regular.woff2 new file mode 100644 index 00000000..3bf98433 Binary files /dev/null and b/_static/fonts/Lato/lato-regular.woff2 differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot new file mode 100644 index 00000000..79dc8efe Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.eot differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf new file mode 100644 index 00000000..df5d1df2 Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.ttf differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff new file mode 100644 index 00000000..6cb60000 Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 new file mode 100644 index 00000000..7059e231 Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-bold.woff2 differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot new file mode 100644 index 00000000..2f7ca78a Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.eot differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf new file mode 100644 index 00000000..eb52a790 Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.ttf differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff new file mode 100644 index 00000000..f815f63f Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff differ diff --git a/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 new file mode 100644 index 00000000..f2c76e5b Binary files /dev/null and b/_static/fonts/RobotoSlab/roboto-slab-v7-regular.woff2 differ diff --git a/_static/jquery.js b/_static/jquery.js new file mode 100644 index 00000000..c4c6022f --- /dev/null +++ b/_static/jquery.js @@ -0,0 +1,2 @@ +/*! jQuery v3.6.0 | (c) OpenJS Foundation and other contributors | jquery.org/license */ +!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType&&"function"!=typeof e.item},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.6.0",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\([^\\r\\n\\f])","g"),ne=function(e,t){var n="0x"+e.slice(1)-65536;return t||(n<0?String.fromCharCode(n+65536):String.fromCharCode(n>>10|55296,1023&n|56320))},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(p.childNodes),p.childNodes),t[p.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&(T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!N[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&(U.test(t)||z.test(t))){(f=ee.test(t)&&ye(e.parentNode)||e)===e&&d.scope||((s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=S)),o=(l=h(t)).length;while(o--)l[o]=(s?"#"+s:":scope")+" "+xe(l[o]);c=l.join(",")}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){N(t,!0)}finally{s===S&&e.removeAttribute("id")}}}return g(t.replace($,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[S]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e&&e.namespaceURI,n=e&&(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:p;return r!=C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),p!=C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.scope=ce(function(e){return a.appendChild(e).appendChild(C.createElement("div")),"undefined"!=typeof e.querySelectorAll&&!e.querySelectorAll(":scope fieldset div").length}),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=S,!C.getElementsByName||!C.getElementsByName(S).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){var t;a.appendChild(e).innerHTML="",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+S+"-]").length||v.push("~="),(t=C.createElement("input")).setAttribute("name",""),e.appendChild(t),e.querySelectorAll("[name='']").length||v.push("\\["+M+"*name"+M+"*="+M+"*(?:''|\"\")"),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+S+"+*").length||v.push(".#.+[+~]"),e.querySelectorAll("\\\f"),v.push("[\\r\\n\\f]")}),ce(function(e){e.innerHTML="";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",F)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},j=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)==(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e==C||e.ownerDocument==p&&y(p,e)?-1:t==C||t.ownerDocument==p&&y(p,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e==C?-1:t==C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]==p?-1:s[r]==p?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if(T(e),d.matchesSelector&&E&&!N[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){N(t,!0)}return 0":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=m[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&m(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function j(e,n,r){return m(n)?S.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?S.grep(e,function(e){return e===n!==r}):"string"!=typeof n?S.grep(e,function(e){return-1)[^>]*|#([\w-]+))$/;(S.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||D,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:q.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof S?t[0]:t,S.merge(this,S.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),N.test(r[1])&&S.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(S):S.makeArray(e,this)}).prototype=S.fn,D=S(E);var L=/^(?:parents|prev(?:Until|All))/,H={children:!0,contents:!0,next:!0,prev:!0};function O(e,t){while((e=e[t])&&1!==e.nodeType);return e}S.fn.extend({has:function(e){var t=S(e,this),n=t.length;return this.filter(function(){for(var e=0;e\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i;ce=E.createDocumentFragment().appendChild(E.createElement("div")),(fe=E.createElement("input")).setAttribute("type","radio"),fe.setAttribute("checked","checked"),fe.setAttribute("name","t"),ce.appendChild(fe),y.checkClone=ce.cloneNode(!0).cloneNode(!0).lastChild.checked,ce.innerHTML="",y.noCloneChecked=!!ce.cloneNode(!0).lastChild.defaultValue,ce.innerHTML="",y.option=!!ce.lastChild;var ge={thead:[1,"","
"],col:[2,"","
"],tr:[2,"","
"],td:[3,"","
"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?S.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;n",""]);var me=/<|&#?\w+;/;function xe(e,t,n,r,i){for(var o,a,s,u,l,c,f=t.createDocumentFragment(),p=[],d=0,h=e.length;d\s*$/g;function je(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&S(e).children("tbody")[0]||e}function De(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function qe(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Le(e,t){var n,r,i,o,a,s;if(1===t.nodeType){if(Y.hasData(e)&&(s=Y.get(e).events))for(i in Y.remove(t,"handle events"),s)for(n=0,r=s[i].length;n").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var _t,zt=[],Ut=/(=)\?(?=&|$)|\?\?/;S.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=zt.pop()||S.expando+"_"+wt.guid++;return this[e]=!0,e}}),S.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Ut.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Ut.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Ut,"$1"+r):!1!==e.jsonp&&(e.url+=(Tt.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||S.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?S(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,zt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((_t=E.implementation.createHTMLDocument("").body).innerHTML="
",2===_t.childNodes.length),S.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=N.exec(e))?[t.createElement(i[1])]:(i=xe([e],t,o),o&&o.length&&S(o).remove(),S.merge([],i.childNodes)));var r,i,o},S.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1").append(S.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},S.expr.pseudos.animated=function(t){return S.grep(S.timers,function(e){return t===e.elem}).length},S.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=S.css(e,"position"),c=S(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=S.css(e,"top"),u=S.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,S.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):c.css(f)}},S.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){S.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===S.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===S.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=S(e).offset()).top+=S.css(e,"borderTopWidth",!0),i.left+=S.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-S.css(r,"marginTop",!0),left:t.left-i.left-S.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===S.css(e,"position"))e=e.offsetParent;return e||re})}}),S.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;S.fn[t]=function(e){return $(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),S.each(["top","left"],function(e,n){S.cssHooks[n]=Fe(y.pixelPosition,function(e,t){if(t)return t=We(e,n),Pe.test(t)?S(e).position()[n]+"px":t})}),S.each({Height:"height",Width:"width"},function(a,s){S.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){S.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return $(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?S.css(e,t,i):S.style(e,t,n,i)},s,n?e:void 0,n)}})}),S.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){S.fn[t]=function(e){return this.on(t,e)}}),S.fn.extend({bind:function(e,t,n){return this.on(e,null,t,n)},unbind:function(e,t){return this.off(e,null,t)},delegate:function(e,t,n,r){return this.on(t,e,n,r)},undelegate:function(e,t,n){return 1===arguments.length?this.off(e,"**"):this.off(t,e||"**",n)},hover:function(e,t){return this.mouseenter(e).mouseleave(t||e)}}),S.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){S.fn[n]=function(e,t){return 0"),n("table.docutils.footnote").wrap("
"),n("table.docutils.citation").wrap("
"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n(''),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.prepend(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current").attr("aria-expanded","false"),t.addClass("current").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current").attr("aria-expanded","true");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").attr("aria-expanded","true");t[0].scrollIntoView()}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").attr("aria-expanded","false"),e.toggleClass("current").attr("aria-expanded",(function(n,e){return"true"==e?"false":"true"})))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t a.language.name.localeCompare(b.language.name)); + + const languagesHTML = ` +
+
Languages
+ ${languages + .map( + (translation) => ` +
+ ${translation.language.code} +
+ `, + ) + .join("\n")} +
+ `; + return languagesHTML; + } + + function renderVersions(config) { + if (!config.versions.active.length) { + return ""; + } + const versionsHTML = ` +
+
Versions
+ ${config.versions.active + .map( + (version) => ` +
+ ${version.slug} +
+ `, + ) + .join("\n")} +
+ `; + return versionsHTML; + } + + function renderDownloads(config) { + if (!Object.keys(config.versions.current.downloads).length) { + return ""; + } + const downloadsNameDisplay = { + pdf: "PDF", + epub: "Epub", + htmlzip: "HTML", + }; + + const downloadsHTML = ` +
+
Downloads
+ ${Object.entries(config.versions.current.downloads) + .map( + ([name, url]) => ` +
+ ${downloadsNameDisplay[name]} +
+ `, + ) + .join("\n")} +
+ `; + return downloadsHTML; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const flyout = ` +
+ + Read the Docs + v: ${config.versions.current.slug} + + +
+
+ ${renderLanguages(config)} + ${renderVersions(config)} + ${renderDownloads(config)} +
+
On Read the Docs
+
+ Project Home +
+
+ Builds +
+
+ Downloads +
+
+
+
Search
+
+
+ +
+
+
+
+ + Hosted by Read the Docs + +
+
+ `; + + // Inject the generated flyout into the body HTML element. + document.body.insertAdjacentHTML("beforeend", flyout); + + // Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout. + document + .querySelector("#flyout-search-form") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); + }) +} + +if (themeLanguageSelector || themeVersionSelector) { + function onSelectorSwitch(event) { + const option = event.target.selectedIndex; + const item = event.target.options[option]; + window.location.href = item.dataset.url; + } + + document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const versionSwitch = document.querySelector( + "div.switch-menus > div.version-switch", + ); + if (themeVersionSelector) { + let versions = config.versions.active; + if (config.versions.current.hidden || config.versions.current.type === "external") { + versions.unshift(config.versions.current); + } + const versionSelect = ` + + `; + + versionSwitch.innerHTML = versionSelect; + versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + + const languageSwitch = document.querySelector( + "div.switch-menus > div.language-switch", + ); + + if (themeLanguageSelector) { + if (config.projects.translations.length) { + // Add the current language to the options on the selector + let languages = config.projects.translations.concat( + config.projects.current, + ); + languages = languages.sort((a, b) => + a.language.name.localeCompare(b.language.name), + ); + + const languageSelect = ` + + `; + + languageSwitch.innerHTML = languageSelect; + languageSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); + } + else { + languageSwitch.remove(); + } + } + }); +} + +document.addEventListener("readthedocs-addons-data-ready", function (event) { + // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav. + document + .querySelector("[role='search'] input") + .addEventListener("focusin", () => { + const event = new CustomEvent("readthedocs-search-show"); + document.dispatchEvent(event); + }); +}); \ No newline at end of file diff --git a/_static/language_data.js b/_static/language_data.js new file mode 100644 index 00000000..c7fe6c6f --- /dev/null +++ b/_static/language_data.js @@ -0,0 +1,192 @@ +/* + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, if available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/_static/minus.png b/_static/minus.png new file mode 100644 index 00000000..d96755fd Binary files /dev/null and b/_static/minus.png differ diff --git a/_static/plus.png b/_static/plus.png new file mode 100644 index 00000000..7107cec9 Binary files /dev/null and b/_static/plus.png differ diff --git a/_static/pygments.css b/_static/pygments.css new file mode 100644 index 00000000..0d49244e --- /dev/null +++ b/_static/pygments.css @@ -0,0 +1,75 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #eeffcc; } +.highlight .c { color: #408090; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #007020; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #007020 } /* Comment.Preproc */ +.highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #FF0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #333333 } /* Generic.Output */ +.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #007020 } /* Keyword.Pseudo */ +.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #902000 } /* Keyword.Type */ +.highlight .m { color: #208050 } /* Literal.Number */ +.highlight .s { color: #4070a0 } /* Literal.String */ +.highlight .na { color: #4070a0 } /* Name.Attribute */ +.highlight .nb { color: #007020 } /* Name.Builtin */ +.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.highlight .no { color: #60add5 } /* Name.Constant */ +.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #007020 } /* Name.Exception */ +.highlight .nf { color: #06287e } /* Name.Function */ +.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ +.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #bb60d5 } /* Name.Variable */ +.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #208050 } /* Literal.Number.Bin */ +.highlight .mf { color: #208050 } /* Literal.Number.Float */ +.highlight .mh { color: #208050 } /* Literal.Number.Hex */ +.highlight .mi { color: #208050 } /* Literal.Number.Integer */ +.highlight .mo { color: #208050 } /* Literal.Number.Oct */ +.highlight .sa { color: #4070a0 } /* Literal.String.Affix */ +.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ +.highlight .sc { color: #4070a0 } /* Literal.String.Char */ +.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */ +.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ +.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.highlight .sx { color: #c65d09 } /* Literal.String.Other */ +.highlight .sr { color: #235388 } /* Literal.String.Regex */ +.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ +.highlight .ss { color: #517918 } /* Literal.String.Symbol */ +.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #06287e } /* Name.Function.Magic */ +.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ +.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ +.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */ +.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/_static/searchtools.js b/_static/searchtools.js new file mode 100644 index 00000000..2c774d17 --- /dev/null +++ b/_static/searchtools.js @@ -0,0 +1,632 @@ +/* + * Sphinx JavaScript utilities for the full-text search. + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename, kind] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +// Global search result kind enum, used by themes to style search results. +class SearchResultKind { + static get index() { return "index"; } + static get object() { return "object"; } + static get text() { return "text"; } + static get title() { return "title"; } +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename, kind] = item; + + let listItem = document.createElement("li"); + // Add a class representing the item's type: + // can be used by a theme's CSS selector for styling + // See SearchResultKind for the class names. + listItem.classList.add(`kind-${kind}`); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms, anchor) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = Documentation.ngettext( + "Search finished, found one page matching the search query.", + "Search finished, found ${resultCount} pages matching the search query.", + resultCount, + ).replace('${resultCount}', resultCount); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; +// Helper function used by query() to order search results. +// Each input is an array of [docname, title, anchor, descr, score, filename, kind]. +// Order the results by score (in opposite order of appearance, since the +// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. +const _orderResultsByScoreThenName = (a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString, anchor) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + for (const removalQuery of [".headerlink", "script", "style"]) { + htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() }); + } + if (anchor) { + const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`); + if (anchorContent) return anchorContent.textContent; + + console.warn( + `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.` + ); + } + + // if anchor not specified or not found, fall back to main content + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent) return docContent.textContent; + + console.warn( + "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.setAttribute("role", "list"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + _parseQuery: (query) => { + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + return [query, searchTerms, excludedTerms, highlightTerms, objectTerms]; + }, + + /** + * execute search (requires search index to be loaded) + */ + _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // Collect multiple result groups to be sorted separately and then ordered. + // Each is an array of [docname, title, anchor, descr, score, filename, kind]. + const normalResults = []; + const nonMainIndexResults = []; + + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase().trim(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + const score = Math.round(Scorer.title * queryLower.length / title.length); + const boost = titles[file] === title ? 1 : 0; // add a boost for document titles + normalResults.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score + boost, + filenames[file], + SearchResultKind.title, + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id, isMain] of foundEntries) { + const score = Math.round(100 * queryLower.length / entry.length); + const result = [ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + SearchResultKind.index, + ]; + if (isMain) { + normalResults.push(result); + } else { + nonMainIndexResults.push(result); + } + } + } + } + + // lookup as object + objectTerms.forEach((term) => + normalResults.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + normalResults.forEach((item) => (item[4] = Scorer.score(item))); + nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item))); + } + + // Sort each group of results by score and then alphabetically by name. + normalResults.sort(_orderResultsByScoreThenName); + nonMainIndexResults.sort(_orderResultsByScoreThenName); + + // Combine the result groups in (reverse) order. + // Non-main index entries are typically arbitrary cross-references, + // so display them after other results. + let results = [...nonMainIndexResults, ...normalResults]; + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + return results.reverse(); + }, + + query: (query) => { + const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query); + const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + SearchResultKind.object, + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + if (!terms.hasOwnProperty(word)) { + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + } + if (!titleTerms.hasOwnProperty(word)) { + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord)) + arr.push({ files: titleTerms[term], score: Scorer.partialTitle }); + }); + } + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (!fileMap.has(file)) fileMap.set(file, [word]); + else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + SearchResultKind.text, + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords, anchor) => { + const text = Search.htmlToText(htmlText, anchor); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/_static/sphinx_highlight.js b/_static/sphinx_highlight.js new file mode 100644 index 00000000..8a96c69a --- /dev/null +++ b/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/general/general.html b/general/general.html new file mode 100644 index 00000000..351d8667 --- /dev/null +++ b/general/general.html @@ -0,0 +1,130 @@ + + + + + + + + + General Information — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

General Information

+

This section is for documenting the general concepts of how Spack-Manager works, +and documentation that is applicable to all users of this software.

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/general/history.html b/general/history.html new file mode 100644 index 00000000..f147a46c --- /dev/null +++ b/general/history.html @@ -0,0 +1,138 @@ + + + + + + + + + History and inspirations for Spack-Manager — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

History and inspirations for Spack-Manager

+

Spack-Manager was created due to the challenges of building the complicated Exawind software stack. +The Exawind codes have a relatively large number of TPL’s and are designed to run on modern HPC architecture, which is currently a moving target. +These factors naturally lead toward using Spack to manage the build dependencies.

+

Arguably the most common use case for Spack is software deployment. +This was the original use for Exawind developers, and a few different extra scripts were maintained for managing the build process for Exawind software. +However, during the Exawind project Spack also released features geared toward development. +This sparked the idea for the central question behind Spack-Manager: how much of our process can we reasonably extend into the Spack ecosystem?

+

Initial evaluations of Spack’s develop features were that there was potential, but also room to grow. +These features have since improved, but the other tenant of Spack-Manager was determined from this trial period: end products need to live as independent from Spack as possible. +This really comes down to the fact that Exawind stack was constantly changing and growing, along with Spack itself. +In reality the entire HPC and computing landscape is changing dramatically, and so our development frameworks need to be moving together, but still have room to independently flex as thing evolve. +In this sense Spack-Manager acts as a buffer in between the larger Spack project, and the invidual software projects that are using Spack-Manager to curate their development process.

+

Spack-Manager’s development obtained a lot of inspiration from the Exawind-Builder project. +Spack-Manager has sought to emulate some of the key features of Exawind-Builder such as the ability to use pre-configured binaries, and to allow users to quickly switch between caches. +Exawind-Builder was a tool principly designed for developers, and Spack-Manager strives to extend that user scope to the entire range of software users.

+

Exawind-Builder is also another example of a tool built on-top of Spack. +However, the strategies of Spack-Manager and Exawind-Builder differ slightly in that Exawind-Builder sought to go around Spack’s missing features through additional bash scripting and environment configurations, while Spack-Manager seeks to predominately extend Spack using the Spack ecosystem for these scenarios. +Both sides have pro’s and con’s. +Choosing to go around Spack makes it easier to customize things with fewer limitations, but it also requires additional code, interfaces and maintenance. +Choosing to conform to Spack infrastructure means accepting some of the limitations and growing pains of the Spack API, but also reducing the amount of infrastructure that needs to be maintained. +This is constantly becoming less of a sacrifice due to the quality of work done by the Spack development team.

+

Spack-Manager is intended to be agile, and adapt to changes in Spack by embracing new features in Spack, and contributing back everything it can to the Spack project. +In this sense we are able to harness the pro’s of Spack, while still customizing our workflow and influencing the growth of Spack in the future.

+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/general/spack_features.html b/general/spack_features.html new file mode 100644 index 00000000..ae9804a3 --- /dev/null +++ b/general/spack_features.html @@ -0,0 +1,267 @@ + + + + + + + + + Important Spack Features — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Important Spack Features

+
+

Spack Specs

+

In Spack the idea of a spec is very important. Specs are descriptors of particular aspects or configurations of a package or packages. +Specs can completely general, merely denoted the name of a package, or they can very specific such as specifying the name of the package with a particular version, with a particular compiler and compiler version, with specific options called variants, as well as constraints on dependencies of the package. +Spack’s documentation has much more information on specs here, but we summarize them here as it is important to utilizing Spack. +Specs are a loose or general form of a configuration for a package. However, Spack is very exact it how it will build and satisfy your requested spec. +It does this through the process of concretization. Concretization maps a spec, no matter how general or specific, into an exact graph of +how Spack will build and fulfill the spec. A command for understanding this process is the spack spec command. Using spack spec +will report to the user how Spack will create a concrete graph or DAG of the package on its dependencies. For example:

+
% spack spec zlib                                                  
+Input spec
+--------------------------------
+zlib
+
+Concretized
+--------------------------------
+zlib@1.2.11%apple-clang@12.0.0+optimize+pic+shared arch=darwin-catalina-skylake
+
+
+

Here we intend to install the zlib package which has no dependencies. If we specify nothing but zlib, this is the configuration Spack has solved +in which it will fulfill the installation of zlib. We can be more specific about our request. Looking at what compilers are available for us in Spack +we can use:

+
% spack compilers
+==> Available compilers
+-- apple-clang catalina-x86_64 ----------------------------------
+apple-clang@12.0.0
+
+-- gcc catalina-x86_64 ------------------------------------------
+gcc@11.2.0
+
+
+

Here we are on a MacOS computer and we have two compilers available. If I prefer zlib be installed using gcc, one can use:

+
% spack spec zlib%gcc
+Input spec
+--------------------------------
+zlib%gcc
+
+Concretized
+--------------------------------
+zlib@1.2.11%gcc@11.2.0+optimize+pic+shared arch=darwin-catalina-skylake
+
+
+

Notice Spack honored our compiler constraint request. Spack reports the concretized spec in a manner that continues to itself be a spec:

+
% spack spec zlib@1.2.11%gcc@11.2.0+optimize+pic+shared arch=darwin-catalina-skylake
+Input spec
+--------------------------------
+zlib@1.2.11%gcc@11.2.0+optimize+pic+shared arch=darwin-catalina-skylake
+
+Concretized
+--------------------------------
+zlib@1.2.11%gcc@11.2.0+optimize+pic+shared arch=darwin-catalina-skylake
+
+
+

Therefore using the spec command helps us to understand specs and what Spack will do with a spec before we use them in other commands. +Here is an example of a more complicated package:

+
% spack spec amr-wind
+Input spec
+--------------------------------
+amr-wind
+
+Concretized
+--------------------------------
+amr-wind@main%apple-clang@12.0.0~cuda~fortran+hypre+internal-amrex~ipo~masa+mpi+netcdf~openfast~openmp~rocm+shared+tests+unit build_type=Release arch=darwin-catalina-skylake
+    ^cmake@3.22.2%apple-clang@12.0.0~doc+ncurses+openssl+ownlibs~qt build_type=Release arch=darwin-catalina-skylake
+        ^ncurses@6.2%apple-clang@12.0.0~symlinks+termlib abi=none arch=darwin-catalina-skylake
+            ^pkgconf@1.8.0%apple-clang@12.0.0 arch=darwin-catalina-skylake
+        ^openssl@1.1.1m%apple-clang@12.0.0~docs certs=system arch=darwin-catalina-skylake
+            ^perl@5.34.0%apple-clang@12.0.0+cpanm+shared+threads arch=darwin-catalina-skylake
+                ^berkeley-db@18.1.40%apple-clang@12.0.0+cxx~docs+stl patches=b231fcc4d5cff05e5c3a4814f6a5af0e9a966428dc2176540d2c05aff41de522 arch=darwin-catalina-skylake
+                ^bzip2@1.0.8%apple-clang@12.0.0~debug~pic+shared arch=darwin-catalina-skylake
+                    ^diffutils@3.8%apple-clang@12.0.0 arch=darwin-catalina-skylake
+                        ^libiconv@1.16%apple-clang@12.0.0 libs=shared,static arch=darwin-catalina-skylake
+                ^gdbm@1.19%apple-clang@12.0.0 arch=darwin-catalina-skylake
+                    ^readline@8.1%apple-clang@12.0.0 arch=darwin-catalina-skylake
+                ^zlib@1.2.11%apple-clang@12.0.0+optimize+pic+shared arch=darwin-catalina-skylake
+    ^hypre@2.23.0%apple-clang@12.0.0~complex~cuda~debug+int64~internal-superlu~mixedint+mpi~openmp+shared~superlu-dist~unified-memory arch=darwin-catalina-skylake
+        ^netlib-lapack@3.9.1%apple-clang@12.0.0~external-blas~ipo+lapacke+shared~xblas build_type=Release arch=darwin-catalina-skylake
+        ^openmpi@4.1.2%apple-clang@12.0.0~atomics~cuda~cxx~cxx_exceptions+gpfs~internal-hwloc~java~legacylaunchers~lustre~memchecker~pmi~pmix+romio~singularity~sqlite3+static~thread_multiple+vt+wrapper-rpath fabrics=none schedulers=none arch=darwin-catalina-skylake
+            ^hwloc@2.7.0%apple-clang@12.0.0~cairo~cuda~gl~libudev+libxml2~netloc~nvml~opencl~pci~rocm+shared arch=darwin-catalina-skylake
+                ^libxml2@2.9.12%apple-clang@12.0.0~python arch=darwin-catalina-skylake
+                    ^xz@5.2.5%apple-clang@12.0.0~pic libs=shared,static arch=darwin-catalina-skylake
+            ^libevent@2.1.12%apple-clang@12.0.0+openssl arch=darwin-catalina-skylake
+            ^openssh@8.8p1%apple-clang@12.0.0 arch=darwin-catalina-skylake
+                ^libedit@3.1-20210216%apple-clang@12.0.0 arch=darwin-catalina-skylake
+    ^netcdf-c@4.7.4%apple-clang@12.0.0~dap~fsync~hdf4~jna+mpi+parallel-netcdf+pic+shared patches=2c88dfbd6d339a0336a43b14a65a1d1df995b853b645e4af612617612a642a53 arch=darwin-catalina-skylake
+        ^hdf5@1.10.7%apple-clang@12.0.0+cxx~fortran+hl~ipo~java+mpi+shared~szip~threadsafe+tools api=default build_type=RelWithDebInfo patches=2a1e3118d7d3d7411820e567b03530de96a46385304017f8e548408aa1cfbfc0 arch=darwin-catalina-skylake
+        ^m4@1.4.19%apple-clang@12.0.0+sigsegv patches=9dc5fbd0d5cb1037ab1e6d0ecc74a30df218d0a94bdd5a02759a97f62daca573,bfdffa7c2eb01021d5849b36972c069693654ad826c1a20b53534009a4ec7a89 arch=darwin-catalina-skylake
+            ^libsigsegv@2.13%apple-clang@12.0.0 arch=darwin-catalina-skylake
+        ^parallel-netcdf@1.12.2%apple-clang@12.0.0~burstbuffer+cxx+fortran+pic+shared arch=darwin-catalina-skylake
+
+
+

It is obvious concretized specs can get large quite quickly. However, Spack is very good at standing on it’s own without requirements +from the existing system. Therefore it can be quite straightforward to build complicated packages on many machines. However, it can also be argued +that this situation involves many packages with Spack will build that may already exist on the machine. While this is fair, we typically solve +this by specifying externals which make Spack aware of packages already existing on the system and utilizing them in its DAG. Spack-manager +has machine-specific configurations provided by its contributors for this purpose. Obtaining a configuration for Spack for the specific machine +and specific project will save the user of Spack a lot of time.

+

In our previous concretized DAG, amr-wind has dependencies on packages. Dependencies in specs are denoted with ^. We can use this to constrain dependencies we would like to request. +For example here we put a constraint on the cmake version:

+
% spack spec amr-wind ^cmake@3.17.0
+Input spec
+--------------------------------
+amr-wind
+    ^cmake@3.17.0
+
+Concretized
+--------------------------------
+amr-wind@main%apple-clang@12.0.0~cuda~fortran+hypre+internal-amrex~ipo~masa+mpi+netcdf~openfast~openmp~rocm+shared+tests+unit build_type=Release arch=darwin-catalina-skylake
+    ^cmake@3.17.0%apple-clang@12.0.0~doc+ncurses+openssl+ownlibs~qt build_type=Release patches=1c540040c7e203dd8e27aa20345ecb07fe06570d56410a24a266ae570b1c4c39,bf695e3febb222da2ed94b3beea600650e4318975da90e4a71d6f31a6d5d8c3d,e51119dd387aa3eb2f21fee730d3aa8b5480301c5e2e3a33bd86f4f7d8903861 arch=darwin-catalina-skylake
+        ^ncurses@6.2%apple-clang@12.0.0~symlinks+termlib abi=none arch=darwin-catalina-skylake
+...
+
+
+

Concretization is an NP-hard problem, so solving the DAG is not instantaneous, and it is very much an active area of research. Spack has +gone through one iteration thus far of updating its concretization strategy. This is the difference between the “original” concretizer and the newer clingo concretizer.

+

Another important idea in Spack is describing the configuration of a particular package involving a complicated DAG into a succint string for the installation directory of the package for example. To do this, Spack collapses several properties of the DAG into a hash. Spack then uses this hash to provide a short form mapping for a particular package and its full description. Spack is a very powerful database of software installations and can be queried to understand the exact state of each package and pinpointing a specific package in which the user is interested. We leave these to the Spack documentation to continue.

+
+
+

Spack Commands

+

Spack has many commands, many of which have great information when adding -h to them. Here we list a few of the most important commands for using within Spack-Manager.

+
    +

  • spack spec -I <spec> : solve the DAG for the spec and show packages in the DAG that are already installed

    • +

  • spack location -i <spec> : used for finding the specific location of an installed package

    • +

  • spack concretize -f : force an activated environment to undergo concretization

    • +

  • spack install : install all packages listed in an environment’s spack.yaml file

    • +

  • spack uninstall <spec>: uninstall specific spec

    • +

  • spack uninstall --dependencies -a -y <spec>: uninstall everything related to a general spec (-a) and all its dependencies without confirming

    • +

  • spack cd -b <spec> : change to build directory of package

    • +

  • spack env activate -d <path> or spacktivate -d <path>: activate a Spack environment at specified path

    • +

  • spack develop <spec> : develop source code in a package locally

    • +

  • spack help --all : list all available Spack commands

    • +

  • spack list <string>: list all available Spack packages matching the string

    • +

  • spack find <spec>: query Spack’s database of installed packages

    • +

  • spack find -Lvd <spec>: list the hashes, variants, and dependencies of the provided spec

    • +

  • spack stage <spec> && spack cd <spec>: download the package’s source code and extract it for browsing

    • +

  • spack docs: open the online spack documentation in a browser

    • +

  • spack -d <spack subcommand>: get debug info on exactly what Spack is doing when it fails

    • +

  • spack config blame packages: show exactly where Spack is obtaining its preferences for things like concretization

    • +

  • spack compilers: list the compilers in which Spack is aware

    • +
+
+
+

Spack Knowledgebase

+

In each package installation directory in spack/opt Spack keeps a .spack directory which contains information on exactly how the package was built.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/general/spack_manager_structure.html b/general/spack_manager_structure.html new file mode 100644 index 00000000..f439f7af --- /dev/null +++ b/general/spack_manager_structure.html @@ -0,0 +1,159 @@ + + + + + + + + + Spack-Manager Structure — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Spack-Manager Structure

+

Spack-Manager is a Spack extension that provides a way for software applications +to configure their usage of spack.

+
+../_images/application-workflow.png + +
+

3 An example of generalized infrastructure requirements that are common across HPC and scientific computing applications. Spack-Manager’s goal is to empower these types of infrastructures while still allowing application teams to drive the details.

+
+
+

The code of Spack-Manager is independent of each individual application and each +application code needs to configure a Spack-Manager Project to tell Spack-Manager how to work +with their application.

+
+../_images/Spack-Manager-Org.png + +
+

4 Spack-Manager is designed to provide an abstraction that can support multiple application teams. Each team develops a Project that can be registered with an instance of Spack-Manager.

+
+
+

A Project at its core is simply a collection of spack configuration files and spack package repositories. +A few other optional hooks will be discussed below.

+

The configuration files in a Project are organized based on the configuration bifurcations that the projects supports. +These are called Machines based on the guiding principle that spack configurations typically have to be +changed when the machine/system is changed.

+

Projects can be registered with Spack-Manager by adding them to the spack-manager.yaml configuration file. +This file lives in the Spack-Manager directory and controls settings for Spack-Manager and the Projects that +are registered.

+
spack-manager:
+  projects:
+    - /path/to/project_a
+      default_view: False
+    - $HOME/project_b
+
+
+

Information on configuring a new Project can be found in the system administrator profile documentation here.

+
+../_images/ApplicationSpace.png + +
+

5 The end goal of many code application and DevOps teams is to efficiently span the space of platform permutations and project variations.

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/genindex.html b/genindex.html new file mode 100644 index 00000000..c530d449 --- /dev/null +++ b/genindex.html @@ -0,0 +1,107 @@ + + + + + + + + Index — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Index
    • +
  • +
    • +
+
+
+
+
+ + +

Index

+ +
+ +
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/index.html b/index.html new file mode 100644 index 00000000..031baab6 --- /dev/null +++ b/index.html @@ -0,0 +1,252 @@ + + + + + + + + + Spack-Manager — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Spack-Manager

+

Spack-Manager is a light-weight extension to +Spack that is intended to streamline the software development and deployment cycle +for software projects on specific machines. +A given software project typically has multiple configurations across many machines. +Spack-Manager is quite literal in its name, in that it provides a way to manage and organize these configurations +across multiple machines, and multiple projets.

+
+_images/Spack-To-Applications.png + +
+

1 Spack is serving the package management needs of thousands of software packages. +However, individual application teams wish to harness the power of Spack for their individual applications specific needs. +This naturally leads to redundant, similar workflows.

+
+
+

The intent of this project is to maintain as thin of a buffer as possible between software packages and Spack, and to be pushing ideas and workflow +improvements back to Spack on a regular basis to reduce the code that is maintained here. +As such we do not try to fully mask Spack’s workflow or commands from users, but rather expose them at a level appropriate for the user type.

+
+

User Profiles

+

Spack-Manager’s design is intended to serve three separate user types in a software project, and the level of expected spack exposure/knowledge required +decreases as the user becomes further removed from the build process. The three user profiles are:

+
    +

  • System administrators (Spack is heavily exposed and relied on)

    • +

  • Code developers (some basics about Spack are required, but much of the workflow can be scripted away)

    • +

  • Analysts (zero exposure to Spack)

    • +
+
+_images/ProfilePyramids.png + +
+

2 Population size of each profile is inverserly proportional to the Spack knowledge required for their roles

+
+
+

Separate documentation exists for each of these user profiles.

+
+ +
+
+
+

Benefits of Spack-Manager

+
    +
  • +
    Spack-Manager allows additional agility and coordination at the project level that can not be maintained for a larger tool/database such as Spack.

    This is done through heavy use of custom Spack package repositories and +Spack’s custom extensions to allow for prototyping at the project level, as well as the option to +maintain features that are only intended for the project’s development team.

    +
    +
    +
    • +
  • +
    Spack-Manager maximizes overlap between the workflows of the three user profiles.

    The main thought behind Spack-Manager is that the exact same infrastructure that the system administrators use to deploy binaries and modules on various machines +can be recycled to run nightly tests, generate time stamped snapshots of binaries for developers to link against, and supply end users +with production executables. +This framework is stitched together through Spack, but the end products (binaries and modules) are designed to be as independent from Spack as possible.

    +
    +
    +
    • +
  • +
    Spack-Manager provides the benefits of Spack by seeking to maintain as small of a wrapper layer as possible. Some of these benefits include:
      +

    • Build reproducibiilty, and scalability

      • +

    • Buy-in and feedback from HPC vendors and software developers over thousands of projects

      • +

    • Support options, extended documentation and testing through the much larger Spack project

      • +
    +
    +
    +
    • +
+

Additional details about the philosophy, and general knowledge can be found in the following documentation section.

+
+ +
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/objects.inv b/objects.inv new file mode 100644 index 00000000..85be2667 --- /dev/null +++ b/objects.inv @@ -0,0 +1,6 @@ +# Sphinx inventory version 2 +# Project: Spack-Manager +# Version: 0.1 +# The remainder of this file is compressed using zlib. +xڭUIo0WXAs6jg#fcd%%-~&DO-,2%miSCWd5Q l@+TDrEԆŀ) ?K>Li "y΃T"w<%㹆^.ݯ%QPe n:Jޘ{Fr(̖KtE?cߓP)5FG,_ϹET*ϣD uUҎ  &:AFY5Lh Bi鋝%'gnڢYGI,G8CYAd?^"Ek)0䢿P_;{Y:2;hsZJk% #7ypbA,l(71n6ie' +-ed WEC#^7QM}6k=,_ʬNKlCߦ_c`h]Ks۶?Ȏwz7IhAF \KGŮ]+32yy)*ǃqP%\gIʧe{'&x~o> \ No newline at end of file diff --git a/search.html b/search.html new file mode 100644 index 00000000..134cf0c9 --- /dev/null +++ b/search.html @@ -0,0 +1,122 @@ + + + + + + + + Search — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+
    +
    • +
  • Search
    • +
  • +
    • +
+
+
+
+
+ + + + +
+ +
+ +
+
+ +
+
+
+
+ + + + + + + + + \ No newline at end of file diff --git a/searchindex.js b/searchindex.js new file mode 100644 index 00000000..e2ba95ff --- /dev/null +++ b/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({"alltitles": {"Adding Version Control": [[12, "adding-version-control"]], "Advanced Topics for Developers": [[6, null]], "Analysts Documentation": [[5, null]], "Anonymous Machines": [[12, "anonymous-machines"]], "Benefits of Spack-Manager": [[4, "benefits-of-spack-manager"]], "Building": [[10, "building"]], "Building and Making Code Changes": [[8, "building-and-making-code-changes"]], "Cleaning Up Old Environments": [[6, "cleaning-up-old-environments"]], "Configuring Machine Auto-detection": [[12, "configuring-machine-auto-detection"]], "Constructing and Utilizing Multiple builds": [[6, "constructing-and-utilizing-multiple-builds"]], "Creating a Project from Scratch": [[12, "creating-a-project-from-scratch"]], "Creating an Environment": [[8, "creating-an-environment"]], "Creating and configuring a Spack-Manager Project": [[12, null]], "Debugging Spack Errors": [[6, "debugging-spack-errors"]], "Developer Documentation": [[9, null]], "Developers: What you need to know about Spack": [[7, null]], "Editing Code": [[10, "editing-code"]], "Environment loading process": [[11, "environment-loading-process"]], "Environment re-use commands": [[11, "environment-re-use-commands"]], "Environment setup commands": [[11, "environment-setup-commands"]], "Environment setup process": [[11, "environment-setup-process"]], "General Information": [[0, null]], "Handling Multiple Environments": [[6, "handling-multiple-environments"]], "History and inspirations for Spack-Manager": [[1, null]], "Important Spack Features": [[2, null]], "Iterating": [[10, "iterating"]], "Major steps of the Spack build process": [[7, "major-steps-of-the-spack-build-process"]], "Managing the Source Code": [[8, "managing-the-source-code"]], "Modifying Specs in an Environment": [[6, "modifying-specs-in-an-environment"]], "Other Commands": [[11, "other-commands"]], "Populating Machine Specific Configurations": [[12, "populating-machine-specific-configurations"]], "Querying the Spack commands": [[7, "querying-the-spack-commands"]], "Quick Start": [[8, "quick-start"]], "Quick-Start: Developer Workflow": [[8, null]], "Reading and writing Spack specs": [[7, "reading-and-writing-spack-specs"]], "Running": [[10, "running"]], "Running Tests and Coming Back": [[8, "running-tests-and-coming-back"]], "Setting up Spack Package Repositories": [[12, "setting-up-spack-package-repositories"]], "Setup": [[10, "setup"]], "Setup Spack-Manager": [[8, "setup-spack-manager"]], "Snapshot Developer Workflow Example": [[10, null]], "Spack Commands": [[2, "spack-commands"]], "Spack Knowledgebase": [[2, "spack-knowledgebase"]], "Spack Specs": [[2, "spack-specs"]], "Spack-Manager": [[4, null]], "Spack-Manager Structure": [[3, null]], "Strategies for Conserving Disk Space": [[6, "strategies-for-conserving-disk-space"]], "System Administrator Documentation": [[13, null]], "Useful Commands for Development": [[11, null]], "User Profiles": [[4, "user-profiles"], [14, null]], "When and How to Use Multiple Instances of Spack-Manager": [[6, "when-and-how-to-use-multiple-instances-of-spack-manager"]], "build-env-dive": [[11, "build-env-dive"]], "quick-activate": [[11, "quick-activate"]], "quick-create": [[11, "quick-create"]], "quick-create-dev": [[11, "quick-create-dev"]], "quick-develop": [[11, "quick-develop"]], "remove-spack-prompt": [[11, "remove-spack-prompt"]]}, "docnames": ["general/general", "general/history", "general/spack_features", "general/spack_manager_structure", "index", "user_profiles/analysts/analysts", "user_profiles/developers/advanced_topics", "user_profiles/developers/developer_spack_minimum", "user_profiles/developers/developer_workflow", "user_profiles/developers/developers", "user_profiles/developers/snapshot_workflow", "user_profiles/developers/useful_commands", "user_profiles/system_admins/creating_a_project", "user_profiles/system_admins/system_admins", "user_profiles/user_profiles"], "envversion": {"sphinx": 64, "sphinx.domains.c": 3, "sphinx.domains.changeset": 1, "sphinx.domains.citation": 1, "sphinx.domains.cpp": 9, "sphinx.domains.index": 1, "sphinx.domains.javascript": 3, "sphinx.domains.math": 2, "sphinx.domains.python": 4, "sphinx.domains.rst": 2, "sphinx.domains.std": 2}, "filenames": ["general/general.rst", "general/history.md", "general/spack_features.md", "general/spack_manager_structure.rst", "index.rst", "user_profiles/analysts/analysts.md", "user_profiles/developers/advanced_topics.md", "user_profiles/developers/developer_spack_minimum.md", "user_profiles/developers/developer_workflow.md", "user_profiles/developers/developers.rst", "user_profiles/developers/snapshot_workflow.md", "user_profiles/developers/useful_commands.md", "user_profiles/system_admins/creating_a_project.md", "user_profiles/system_admins/system_admins.rst", "user_profiles/user_profiles.rst"], "indexentries": {}, "objects": {}, "objnames": {}, "objtypes": {}, "terms": {"": [1, 2, 3, 4, 6, 7, 8, 10, 11, 12], "0": [2, 7, 10, 12], "00": 10, "01": 10, "05": 10, "07": 10, "08": 10, "1": [2, 7, 8, 10], "10": [2, 7, 10], "100": 10, "1001": 10, "11": [2, 7, 10], "11020": 10, "116": 10, "12": [2, 7, 10], "1256": 10, "13": [2, 7, 10], "1345": 10, "14": 10, "15": 10, "150589": 10, "155": 10, "16": [2, 8], "16gb": 10, "17": 2, "18": [2, 10], "19": 2, "1c540040c7e203dd8e27aa20345ecb07fe06570d56410a24a266ae570b1c4c39": 2, "1e": 10, "1m": [2, 10], "2": [2, 8, 10], "20": 7, "2020": 10, "20210216": 2, "2022": 10, "21": 7, "22": [2, 10], "23": 2, "237": 10, "2476": 10, "26": 10, "2610": 10, "27": 10, "2a1e3118d7d3d7411820e567b03530de96a46385304017f8e548408aa1cfbfc0": 2, "2c88dfbd6d339a0336a43b14a65a1d1df995b853b645e4af612617612a642a53": [2, 10], "3": [2, 7, 8, 10, 12], "30": [7, 10], "32": 7, "32m": 10, "33": 10, "34": 2, "35": 7, "354065": 10, "3576e5f3d6b34d8bc8c8c8f2749127ece1ce89b": 10, "37": 7, "38": 10, "4": [2, 7, 8, 10, 11], "40": 2, "426": 10, "478": 10, "48": 10, "4m": 10, "5": [2, 7, 10, 11], "50": 7, "52": 7, "53": 7, "59": 10, "5agjw2c": 10, "5agjw2cs2kprcw2xm5ffmrojfc7aknnz": 10, "5muy3vijyqputqmbdyzhltqot3fvwibu": 10, "6": [2, 10], "60": 7, "61": 7, "62": 7, "7": [2, 10, 11], "70": [7, 10], "72": 7, "75": 7, "78": 10, "8": [2, 10], "80": 7, "86": 7, "8p1": 2, "9": [2, 7, 10], "9dc5fbd0d5cb1037ab1e6d0ecc74a30df218d0a94bdd5a02759a97f62daca573": 2, "A": [2, 3, 4, 6, 7, 11, 12], "As": [4, 7, 11, 12], "At": [8, 12], "For": [2, 6, 7, 8, 11, 12], "If": [2, 6, 7, 8, 10, 11, 12], "In": [1, 2, 6, 8, 10, 11, 12], "It": [2, 6, 7, 8, 10, 11, 12], "No": [10, 12], "One": [6, 10], "THe": 10, "The": [1, 3, 4, 5, 6, 7, 8, 10, 11, 12], "Then": 10, "There": [6, 8, 10, 11, 12], "These": [1, 3, 5, 7, 8, 11, 12], "To": [2, 5, 6, 7, 8, 10, 11, 12], "With": [8, 10], "__pycache__": 12, "abi": 2, "abiilti": 11, "abil": 1, "abl": [1, 8, 10], "about": [2, 4, 6, 8, 9, 10, 14], "abov": [6, 7, 8, 12], "abs_tol": 10, "absolut": 8, "abstract": 3, "accept": [1, 11], "acces": 8, "access": 8, "across": [3, 4, 12], "act": 1, "actic": 8, "activ": [2, 6, 7, 8, 9, 10], "actual": 12, "ad": [2, 3, 4, 6, 7, 8, 11, 13], "adapt": 1, "add": [5, 6, 7, 8, 10, 11, 12], "addit": [1, 4, 6, 8, 12], "address": 7, "adequ": 8, "adios2": 10, "administr": [3, 4, 5, 7, 14], "advanc": [4, 9, 14], "advantag": 10, "after": [8, 10, 11], "again": [6, 7, 10], "against": [4, 11], "agil": [1, 4], "air": 8, "align": 7, "all": [0, 2, 6, 7, 8, 11, 12], "allow": [1, 3, 4, 6, 7, 8, 10, 11, 12], "almost": 10, "along": [1, 7, 10, 11, 12], "alreadi": [2, 10, 11], "also": [1, 2, 6, 7, 8, 10, 11, 12], "alwai": [7, 10], "amd": 7, "amdgpu": 7, "amdgpu_target": 7, "ameso": 10, "amesos2": 10, "amount": 1, "amr": [2, 6, 7, 8, 11], "amrex": [2, 7], "an": [2, 3, 4, 7, 9, 10, 11, 12], "analyst": [4, 14], "anasazi": 10, "ani": [6, 7, 8, 10, 11, 12], "anoth": [1, 2], "answer": 7, "anticip": [11, 12], "anyon": 5, "anyth": [6, 7], "anytim": 8, "api": [1, 2], "app": 7, "appl": [2, 12], "appli": 11, "applic": [0, 3, 4, 12], "appropri": [4, 12], "ar": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], "arbitrari": [6, 10, 12], "arch": [2, 10], "archaic": 6, "architectur": [1, 7], "archiv": 6, "area": 2, "arg": 8, "argu": 2, "arguabl": [1, 7], "argument": [6, 7, 8, 10, 11, 12], "around": 1, "arrai": 7, "asan": [7, 10], "aspect": 2, "assist": 11, "associ": [7, 12], "assum": 8, "atom": 2, "attribut": 10, "auto": [4, 13], "autocomplet": 12, "automat": [6, 7, 8, 10, 12], "autonomi": 7, "autoreconf": 10, "avail": [2, 5, 7, 8, 10, 11, 12], "awai": [4, 6], "awar": [2, 11], "aztec": 10, "b": [2, 7, 8, 10, 11], "b231fcc4d5cff05e5c3a4814f6a5af0e9a966428dc2176540d2c05aff41de522": 2, "b5pippu": 10, "b5pippuk6fzbpysv24phtw4etslotbs6": 10, "back": [1, 4, 6, 7, 9, 11], "base": [3, 6, 8, 11, 12], "bash": [1, 7, 10, 11], "bash_profil": 8, "bashrc": 6, "basi": 4, "basic": [4, 7, 9, 10, 12], "basickokko": 10, "basker": 10, "becaus": [6, 7, 8, 12], "becom": [1, 4, 6, 11], "been": [6, 10, 11, 12], "befor": [2, 6, 8, 12], "behav": 11, "behavior": [7, 8, 11, 12], "behind": [1, 4], "being": [6, 10, 11], "belo": 10, "below": [3, 6, 8, 11], "benefit": 7, "berkelei": 2, "beta": 8, "between": [1, 2, 4, 6], "bf695e3febb222da2ed94b3beea600650e4318975da90e4a71d6f31a6d5d8c3d": 2, "bfdffa7c2eb01021d5849b36972c069693654ad826c1a20b53534009a4ec7a89": 2, "bifurc": [3, 12], "binari": [1, 4, 6, 10, 11], "bit": 6, "bla": [2, 10], "blacklist": 10, "blame": 2, "block": 10, "blow": 6, "boolean": [7, 12], "boost": 10, "bootstrap": 8, "both": [1, 6, 8, 10], "branch": [7, 8, 10, 11], "brief": 7, "broadest": 7, "brows": 2, "browser": 2, "buffer": [1, 4], "bug": 6, "bui": 4, "build": [1, 2, 4, 5, 9, 12], "build0": 6, "build_stag": 12, "build_typ": [2, 6, 7, 10], "builder": 1, "built": [1, 2, 6, 7, 10, 11], "builtin": 12, "burstbuff": 2, "bzip2": 2, "c": [2, 7, 10], "cach": [1, 12], "cairo": 2, "call": [2, 3, 6, 8, 10, 11], "can": [1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 12], "capabl": 10, "captur": 8, "case": [1, 6, 8, 12], "cat": 12, "catalina": 2, "catalyst": 10, "catch": 6, "caus": [6, 8], "caution": 11, "cd": [2, 7, 8, 10, 11], "cee": 5, "centos7": 10, "central": 1, "cert": 2, "chaco": 10, "challeng": 1, "chang": [1, 2, 3, 4, 6, 9, 10, 11], "check": [6, 8, 10, 11, 12], "checkcoords1elem": 10, "checkout": [8, 10], "choos": [1, 10], "ci73hai": 10, "ci73hainzvjnag2ynsg7jxvaotnflz": 10, "clang": [2, 7, 10, 12], "clangtidi": 7, "clariti": 7, "clean": [4, 9, 10, 11], "clingo": [2, 8, 10, 12], "clone": [7, 8, 10, 11], "clunkier": 11, "cmake": [2, 6, 7, 10], "cmakepackag": 7, "code": [1, 2, 3, 4, 6, 7, 9, 11, 12], "collaps": 2, "collect": [3, 12], "column": 12, "com": [7, 8, 10], "combin": [7, 8, 10], "come": [1, 4, 7, 9, 11, 12], "comfort": 6, "command": [0, 4, 5, 6, 8, 9, 10, 12, 14], "commit": 10, "commnand": 7, "common": [1, 3, 6, 8, 11], "commonli": 11, "commun": 7, "compil": [2, 6, 7, 10, 12], "complain": 10, "complet": [2, 7, 11, 12], "complex": [2, 6, 10], "complic": [1, 2], "compnent": 11, "compon": 11, "compress": 10, "comput": [1, 2, 3, 10], "con": 1, "concept": [0, 6, 7], "concis": [8, 10], "concret": [2, 6, 7, 8, 10, 11, 12], "conda": [7, 8], "config": [2, 6, 8, 12], "configr": 12, "configur": [1, 2, 3, 4, 6, 7, 8, 10, 11, 13, 14], "confirm": [2, 8], "conflict": [6, 7], "conform": 1, "confus": 7, "conncret": 6, "conserv": [4, 9], "constantli": 1, "constrain": [2, 7, 12], "constraint": [2, 11], "construct": [4, 9, 11], "contain": [2, 6, 7], "continu": [2, 10], "contribut": 1, "contributor": 2, "control": [3, 4, 8, 11, 13], "conveni": [7, 10, 11], "convent": 12, "coordin": 4, "copi": [8, 12], "copy_repo": 12, "core": 3, "correct": 11, "could": [6, 12], "count": 10, "coupl": 12, "cover": [7, 8], "cpanm": 2, "cpp": 10, "cppcheck": 7, "cpu": 7, "creat": [1, 2, 4, 5, 6, 7, 9, 10, 13, 14], "creation": 6, "criteria": 12, "critic": 7, "ctest": [6, 8, 11], "cuda": [2, 6, 7, 10], "cuda_arch": [7, 10], "cuda_rdc": 10, "cuda_vers": 10, "curat": [1, 7], "curiou": 8, "current": [1, 6, 7, 8, 10, 12], "custom": [1, 4, 5, 7, 8, 11, 12], "cwar5vn": 10, "cwar5vnomowwdorf57nay6e7erladdbi": 10, "cxx": 2, "cxx_except": 2, "cxxstd": 10, "cycl": [4, 7, 10], "d": [2, 6, 8, 10, 12], "dag": [2, 7, 10], "dap": [2, 10], "darwin": [2, 12], "databas": [2, 4, 6], "date": [6, 8, 10, 12], "db": 2, "debug": [2, 4, 7, 9, 10], "decid": [7, 10], "decreas": 4, "def": 12, "default": [2, 6, 7, 8, 10, 11, 12], "default_view": 3, "defin": [7, 8, 10], "definit": 6, "delet": 6, "delimit": 7, "delin": 12, "delta": 10, "demo": [8, 12], "demonstr": 12, "denot": 2, "depend": [1, 2, 6, 7, 8, 10, 11, 12], "deploi": [4, 5], "deploy": [1, 4, 12], "deprec": 7, "describ": [2, 12], "descript": [2, 7], "descriptor": 2, "design": [1, 3, 4, 5, 6, 11, 12], "desir": [11, 12], "detail": [3, 4, 7, 8, 10], "detect": [4, 7, 13], "detector": 12, "determin": [1, 7], "dev": [7, 8, 9, 10], "dev_path": 10, "develop": [1, 2, 3, 4, 12, 13, 14], "devop": 3, "dictionari": [7, 12], "differ": [1, 2, 6, 8, 11], "diffutil": 2, "dir": [7, 8], "directli": 10, "directori": [2, 3, 5, 6, 7, 8, 10, 11, 12], "dirti": 10, "discourag": 6, "discover_execution_spac": 10, "discuss": [3, 7], "disk": [4, 9], "displai": 8, "dist": [2, 10], "dive": [6, 8, 9], "do": [2, 4, 6, 7, 8, 10, 11], "doc": [2, 10], "document": [0, 2, 3, 4, 7, 8, 10, 14], "documentaiton": 8, "doe": [2, 7, 8], "doesn": [6, 11], "don": [6, 7, 8, 10, 11], "done": [1, 4, 5, 6, 7, 8, 10], "down": [1, 11], "download": [2, 7], "dramat": 1, "drive": 3, "driver": 8, "drop": 11, "dtk": 10, "due": [1, 8], "dure": 1, "dynam": 6, "e": [6, 7, 10, 11], "e4": 12, "e51119dd387aa3eb2f21fee730d3aa8b5480301c5e2e3a33bd86f4f7d8903861": 2, "e9142052b09d6a6ddecbe9b83dedd1f7b4588fac": 10, "each": [2, 3, 4, 6, 7, 8, 10, 12], "eagl": [5, 10], "eaglef": 10, "earliest": 10, "easi": 7, "easier": 1, "easili": [10, 12], "echo": [8, 10, 11], "ecom": 10, "ecosystem": 1, "ecp": 7, "edit": [4, 6, 8, 9, 11], "editor": 6, "effect": [7, 11], "effici": [3, 11], "either": [6, 7, 8], "el1": 10, "element": 7, "els": 12, "emac": 6, "email": 6, "embrac": 1, "empow": 3, "empti": 12, "emul": [1, 7], "enabl": [7, 8, 10], "enclos": 7, "encount": 6, "encourag": 6, "end": [1, 3, 4, 6, 13], "enforc": 7, "ensur": [7, 12], "enter": 10, "entir": [1, 6, 8, 10, 11], "entri": 12, "enumer": 10, "env": [2, 6, 7, 8, 9, 10, 12], "environ": [1, 2, 4, 5, 7, 9, 10, 12], "environments_root": 8, "epetra": 10, "epetraext": 10, "epetraextbtf": 10, "epetraextexperiment": 10, "epetraextgraphreord": 10, "equivalenc": 7, "error": [4, 9], "essenti": [6, 7], "etc": [6, 7, 10, 11], "evalu": [1, 12], "even": 7, "ever": 7, "everi": [6, 7, 12], "everyth": [1, 2, 6], "evolv": 1, "ex": 10, "exact": [2, 4], "exactli": [2, 8, 10, 11], "exampl": [1, 2, 3, 4, 6, 7, 8, 9, 12, 14], "exawind": [1, 5, 7, 8, 10, 11, 12], "execut": [4, 5, 7, 8, 10, 11], "exisit": 8, "exist": [2, 4, 6, 8, 10, 12], "exit": [6, 7, 8, 11], "exodu": 10, "expand": 12, "expect": 4, "explic": 10, "explicit_template_instanti": 10, "export": [6, 8, 10], "expos": 4, "exposur": 4, "extend": [1, 4], "extens": [3, 4, 12], "extern": [2, 7, 8, 10, 11], "extra": [1, 8], "extract": 2, "f": [2, 6, 10], "fabric": 2, "fact": 1, "factor": 1, "fail": [2, 11], "fair": 2, "fairli": 10, "fall": 7, "fals": [3, 6, 7, 12], "familiar": [8, 11], "far": [2, 12], "faster": 6, "fastest": [7, 11], "featur": [0, 1, 4, 6, 7, 8, 11], "feedback": 4, "fetch": [8, 10], "few": [1, 2, 3], "fewer": 1, "ffdad9a639ff490da5bd4f254e3a849b9dbf39cf7d28f8ed4419a05048846cf6": 10, "fftw": 10, "file": [2, 3, 5, 6, 7, 8, 10, 11, 12], "filesystem": [6, 12], "filesytem": 8, "final": [6, 8], "find": [2, 10, 12], "first": [7, 8, 10, 11, 12], "fix": [10, 12], "flag": [6, 7, 8, 10, 11, 12], "flavor": 12, "flex": 1, "flexibl": 8, "float": 10, "flow": 8, "focu": 10, "focus": 8, "follow": [4, 6, 7, 10, 11, 12], "forc": [2, 10], "forget": [7, 8], "fork": [8, 11], "form": [2, 12], "fortran": [2, 10, 12], "forward": [6, 7, 8], "found": [3, 4, 7, 10, 12], "framework": [1, 4], "free": [8, 12], "freeli": 11, "frequent": 6, "from": [1, 2, 4, 6, 7, 8, 10, 11, 13], "fsync": [2, 10], "fulfil": [2, 10], "full": 2, "fullfil": 10, "fulli": [4, 11], "function": [6, 8, 11, 12], "fundament": 7, "further": [4, 8], "futur": [1, 10, 12], "g": 10, "g4tc7v2": 10, "g4tc7v27alixmh2ail3lud3iweclbf52": 10, "ga66bb9c6fa4": 10, "gape": 8, "gcc": [2, 7, 10, 12], "gdbm": 2, "gear": 1, "gener": [2, 3, 4, 5, 6, 7, 10, 11], "get": [2, 6, 7, 8, 11, 12], "gfx1010": 7, "gfx1011": 7, "gfx1012": 7, "gfx701": 7, "gfx801": 7, "gfx802": 7, "gfx803": 7, "gfx900": 7, "gfx906": 7, "gfx908": 7, "gfx90a": 7, "git": [6, 7, 8, 10, 11, 12], "github": [6, 7, 8, 10], "gitignor": 12, "give": [6, 7, 8, 11], "given": [4, 8, 11, 12], "gl": 2, "global": 10, "go": [1, 6, 7, 8, 12], "goal": 3, "gone": 2, "good": [2, 6], "gotyp": 10, "gpf": 2, "gptune": 10, "gpu": [7, 10], "granular": 11, "graph": [2, 6, 7, 10, 11], "great": 2, "greater": 8, "grow": 1, "growth": 1, "gtest": 10, "guard": 6, "guid": 3, "h": [2, 7, 8, 11], "ha": [1, 2, 4, 6, 7, 8, 10, 11, 12], "had": [7, 11], "hand": 7, "handl": [4, 9], "happen": [8, 10], "har": [1, 4], "hard": 2, "hash": [2, 6], "hasn": 6, "have": [1, 2, 3, 6, 7, 8, 10, 11, 12], "hdf4": [2, 10], "hdf5": [2, 10], "heavi": [4, 6], "heavili": 4, "help": [2, 6, 7, 8, 9, 11], "here": [2, 3, 4, 6, 7, 8, 10, 11, 12], "hierarchi": 12, "higher": 12, "highli": 12, "hip": 7, "histori": [0, 4], "hl": 2, "hog": 6, "hold": 12, "holder": 12, "home": 3, "homepag": 7, "honor": 2, "hook": 3, "how": [0, 1, 2, 3, 4, 7, 8, 9, 10, 12], "howev": [1, 2, 4, 6, 8, 10, 12], "hpacf": 10, "hpc": [1, 3, 4, 5, 10], "hpe": 10, "hsa": 7, "http": [7, 10, 12], "hwloc": 2, "hypr": [2, 6, 7, 10, 12], "hypre_parcsr_mgr": 10, "i": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13], "idea": [1, 2, 4, 6], "ideal": 8, "ifpack": 10, "ifpack2": 10, "ignor": 12, "illustr": 6, "immedi": 7, "implement": 12, "implementd": 8, "import": [0, 4, 7, 12], "improv": [1, 4, 6], "includ": [4, 6, 7, 8, 10, 12], "incompat": 6, "inconsist": 6, "increment": [6, 8], "independ": [1, 3, 4, 12], "indic": 12, "individu": [3, 4, 11], "inevit": 6, "influenc": 1, "info": [2, 7, 10], "inform": [2, 3, 4, 6, 7, 10, 11], "infrastructur": [1, 3, 4, 5], "initi": [1, 10, 12], "input": [2, 7], "insid": [6, 8, 12], "insight": 6, "inspect": 8, "inspir": [0, 4], "instal": [2, 6, 7, 8, 10, 11, 12], "install_tre": 6, "instanc": [3, 4, 7, 9, 12], "instantan": 2, "int64": [2, 10], "integr": 7, "intel": 10, "intend": [1, 2, 4, 7, 11], "intent": [4, 7, 8], "inter": 6, "interest": 2, "interfac": [1, 8], "intern": [2, 7, 10], "interprocedur": 7, "intrepid": 10, "intrepid2": 10, "introduct": 7, "inverserli": 4, "invidu": 1, "involv": [2, 6], "io": 12, "ipo": [2, 7, 10], "isorropia": 10, "issu": [6, 8, 11], "item": 7, "iter": [2, 4, 9, 11], "its": [2, 3, 4, 12], "itself": [1, 2, 7, 10], "j": 8, "j16": 8, "j8": 6, "java": 2, "jna": [2, 10], "jrood": 7, "jroverf": 10, "jump": 6, "just": [5, 6, 7, 8, 11, 12], "k": 10, "keep": [2, 6, 11], "kei": [1, 6, 7, 12], "kept": 12, "kib": 10, "know": [4, 8, 9, 11, 14], "knowledg": [4, 7], "knowledgebas": [0, 4], "known": 12, "known_machin": 12, "kokko": 10, "kokkos_enable_cuda": 10, "l": [6, 12], "lambda": 12, "landscap": 1, "languag": 7, "lapack": [2, 10], "larg": [1, 2, 7], "larger": [1, 4], "last": 12, "lastli": 10, "later": 8, "latest": [10, 11], "launch": [8, 11], "law": 12, "layer": 4, "lead": [1, 4, 6], "learn": [7, 8], "least": 11, "leav": 2, "left": [7, 8], "legacylaunch": 2, "less": 1, "let": [10, 11, 12], "level": [4, 7, 8, 12], "lh": 12, "lib": 2, "libedit": 2, "libev": 2, "libiconv": 2, "librari": [6, 7], "libsigsegv": 2, "libudev": 2, "libxml2": 2, "light": 4, "like": [2, 6, 7, 10, 11, 12], "limit": 1, "line": [6, 8], "link": [4, 6, 7, 11], "linux": 10, "list": [2, 5, 7, 8, 11, 12], "liter": 4, "littl": 8, "live": [1, 3, 12], "ll": 12, "llvm": 7, "load": [4, 6, 9], "locaiton": 8, "local": [2, 6, 10, 12], "locat": [2, 5, 6, 7, 8, 10, 11, 12], "log": 6, "long": [10, 11], "look": [2, 7, 10, 12], "loos": [2, 10, 12], "lot": [1, 2, 7], "lustr": [2, 10], "lvd": 2, "m": [7, 8, 10], "m4": 2, "maachin": 12, "machin": [2, 3, 4, 5, 6, 8, 10, 11, 13], "maco": 2, "macro": 10, "mai": [2, 6, 7, 8, 10, 12], "main": [2, 4, 6, 7, 8, 10, 11], "mainli": 12, "maintain": [1, 4, 7], "mainten": 1, "major": [4, 5, 9], "make": [1, 2, 4, 6, 7, 9, 10, 11, 12], "manag": [0, 2, 5, 7, 9, 10, 11, 13, 14], "mani": [2, 3, 4, 6, 10, 11], "manipul": [7, 11], "manner": [2, 8], "manual": [8, 10, 11, 12], "map": [2, 10], "masa": [2, 7], "mask": 4, "master": [6, 7, 8, 10], "match": [2, 6, 7, 8, 11, 12], "matplotlib": 7, "matter": 2, "maxim": 4, "mean": [1, 6, 7, 8, 10, 11, 12], "meet": 12, "memcheck": 2, "memori": [2, 10], "mere": 2, "merg": 10, "mesh": 7, "mesquit": 10, "messag": [6, 7, 8], "method": 12, "mib": 10, "michaeljbrazel": 7, "might": 8, "mind": 11, "mine": 10, "minim": 7, "minimum": 7, "minitensor": 10, "minsizerel": 7, "mirror": 12, "misc_cach": 12, "miss": 1, "mix": 6, "mixedint": [2, 10], "mkdir": [8, 12], "ml": 10, "mode": 6, "modern": 1, "modifi": [4, 7, 9, 12], "modul": [4, 5, 7, 10], "modulepath": 5, "moment": 12, "more": [2, 6, 7, 8, 11, 12], "most": [1, 2, 7, 8, 11, 12], "move": [1, 8, 11], "mpi": [2, 7, 10, 12], "mpich": 12, "mpt": 10, "much": [1, 2, 4, 6, 11], "muelu": 10, "multi": 11, "multipl": [3, 4, 7, 8, 9], "multistep": 8, "mump": 10, "must": [7, 12], "my": [6, 7, 8], "n": [6, 8, 10], "nalu": [6, 8, 10], "name": [2, 4, 5, 6, 7, 8, 10, 11, 12], "natur": [1, 4], "nccmp": 10, "ncurs": [2, 10], "necessari": [10, 12], "necessarili": 8, "need": [1, 3, 4, 5, 6, 8, 9, 10, 11, 12, 14], "netcdf": [2, 7, 10], "netlib": [2, 10], "netloc": 2, "new": [1, 3, 6, 7, 8, 10, 11, 12], "newer": [2, 8], "next": [7, 8, 10, 12], "nice": 6, "nightli": 4, "node": 10, "non": [6, 7, 11, 12], "none": [2, 7], "nontemplatenodalgradpopenbc": 10, "nopt": 10, "normal": 7, "note": [8, 11, 12], "noth": [2, 10, 12], "notic": [2, 6, 10], "now": [6, 7, 10, 12], "nox": 10, "np": 2, "nrel": [7, 10], "nuanc": 6, "number": [1, 11, 12], "nvcc": 10, "nvml": 2, "object": 10, "obtain": [1, 2, 7, 10], "obviou": 2, "occur": 8, "off": [6, 7, 8, 11], "ok": 10, "okai": 11, "old": [4, 8, 9], "omit": 6, "ommit": 8, "onc": [6, 7, 8, 10, 11, 12], "one": [2, 6, 7, 8, 10, 11, 12], "ones": 6, "onli": [4, 6, 8, 10, 12], "onlin": 2, "open": [2, 6, 11], "opencl": 2, "openfast": [2, 6, 7, 8, 10], "openmp": [2, 7, 10], "openmpi": [2, 12], "openssh": 2, "openssl": [2, 10], "oper": 12, "opt": [2, 6, 10], "optim": [2, 7], "option": [2, 3, 4, 6, 7, 8, 10, 11, 12], "option2": 8, "order": 10, "organ": [3, 4, 7, 10, 12], "origin": [1, 2, 10, 11], "other": [1, 2, 3, 4, 6, 7, 9, 10], "our": [1, 2, 6, 7, 10], "out": [6, 7, 10], "outlin": 8, "output": 12, "outsid": [8, 11], "over": [4, 6, 7, 8, 11], "overhead": [8, 10], "overlap": 4, "overridden": 12, "overset": 8, "overview": 7, "overwritten": 10, "own": [2, 12], "ownlib": [2, 10], "p": [7, 10], "p2fnhpz": 10, "p2fnhpzbpg7wtriqqsbudgtdwgtcrud3": 10, "pack": 10, "packag": [2, 3, 4, 6, 7, 8, 10, 11, 13], "page": 7, "pain": 1, "pair": 12, "panda": 7, "parallel": [2, 10], "parallel_for": 10, "paramet": [6, 10], "parent": 12, "parenthesi": 11, "part": 7, "particular": 2, "pass": [6, 7, 11], "past": 6, "patch": [2, 10], "path": [2, 3, 5, 6, 8, 10, 11, 12], "pci": 2, "pcie": 10, "penalti": 8, "pend": 11, "peopl": 5, "per": 10, "perform": [6, 10, 11], "period": [1, 6], "perl": 2, "permut": 3, "person": [6, 12], "pertin": 6, "phalanx": 10, "phase": [7, 10], "philosophi": 4, "pic": [2, 10], "pick": [8, 12], "pile": 6, "pinpoint": 2, "piro": 10, "pkgconf": 2, "place": [6, 10, 12], "plan": [8, 10], "platform": [3, 12], "pleas": [8, 10, 11, 12], "pmi": 2, "pmix": 2, "point": [7, 8, 11, 12], "popul": [4, 8, 13], "popular": 12, "posit": [7, 12], "possibl": [1, 4, 6, 7, 10], "potenti": [1, 11], "power": [2, 4], "practic": [7, 11], "pre": [1, 8, 11, 12], "prebuilt": 10, "preced": 12, "preconfigur": 5, "predomin": 1, "prefer": [2, 6, 7, 12], "prefix": 7, "preserv": 6, "previou": [2, 7, 10], "previous": 7, "princip": 11, "principl": 3, "principli": 1, "print": 7, "pro": 1, "probabl": 11, "problem": [2, 7], "problemat": 6, "proceed": 8, "process": [1, 2, 4, 8, 9, 10, 12, 13], "product": [1, 4, 6], "profil": 3, "project": [1, 2, 3, 4, 5, 7, 9, 10, 13, 14], "project_a": 3, "project_b": 3, "projet": 4, "prompt": [8, 9], "prone": 6, "properli": 12, "properti": 2, "proport": 4, "prototyp": 4, "provid": [2, 3, 4, 7, 8, 10, 11, 12], "prune": 6, "psakiev": 12, "psakievich": 8, "pull": 10, "purpos": [2, 8], "pursu": 10, "push": [4, 6, 10, 12], "put": [2, 6], "pwd": 8, "py": [7, 12], "pyc": 12, "python": [2, 7, 10, 11, 12], "qt": [2, 10], "qualiti": 1, "queri": [2, 4, 9], "question": [1, 7], "quick": [4, 6, 7, 9, 10, 14], "quick_command": [8, 11], "quickli": [1, 2], "quit": [2, 4, 6], "r": [6, 7, 8], "r103u23": 10, "rail": 6, "rang": 1, "rapid": 11, "rather": [4, 7], "rbzxf3n": 10, "rbzxf3nbmxodxvgvtq72n22glbd7wpdx": 10, "rcfile": [10, 11], "re": [4, 7, 8, 9, 10, 12], "reach": 6, "read": [4, 6, 9], "readlin": 2, "realiti": 1, "realli": [1, 6, 8, 11, 12], "reason": 1, "rebuild": [6, 8, 10], "rebuilt": 10, "receiv": 10, "recommend": [6, 7, 8, 10], "reconcret": 6, "recurs": [8, 10], "recycl": 4, "reduc": [1, 4], "redund": [4, 11], "refer": [7, 8, 11, 12], "referenc": 10, "refresh": 8, "regist": [3, 10], "regress": [7, 8], "regular": [4, 10], "rel": [1, 7, 12], "rel_tol": 10, "relat": [2, 11], "releas": [1, 2, 6, 7, 10], "reli": 4, "relink": 10, "relwithdebinfo": [2, 7], "remain": 11, "rememb": 7, "remind": [7, 11, 12], "remot": [8, 10], "remov": [4, 6, 9, 10], "renam": 10, "replac": 8, "repo": [6, 8, 10, 11, 12], "report": 2, "repositori": [3, 4, 13], "reproduc": 11, "reproducibiilti": 4, "request": 2, "requir": [1, 2, 3, 4, 7, 9, 10, 11, 12], "research": 2, "reserv": 12, "resolut": 12, "resolv": [10, 12], "rest": [6, 10], "restrict": 7, "retain": 7, "return": [11, 12], "reus": [6, 10, 12], "review": 8, "revis": 6, "rf": 6, "right": [6, 7], "rm": [6, 10], "rocm": [2, 7, 10], "rocr": 7, "rol": 10, "role": 4, "romio": 2, "room": 1, "root": [6, 7, 8, 10, 11], "root_spack": 6, "row": 8, "rpath": 2, "run": [1, 4, 5, 6, 7, 9, 11, 12], "rythmo": 10, "sacado": 10, "sacrific": 1, "safe": 7, "sai": [6, 8], "same": [4, 6, 7, 8, 11, 12], "sandialab": [8, 10], "sanit": 7, "satisfi": 2, "save": 2, "scalabl": 4, "scenario": [1, 6, 11], "schedul": 2, "scientif": 3, "scope": 1, "scorec": 10, "scratch": [4, 6, 10, 13], "script": [1, 4, 7, 8, 11, 12], "seamless": 12, "section": [0, 4, 6, 7, 8, 9, 12, 13], "see": [6, 7, 8, 10, 11, 12], "seek": [1, 4], "seem": 7, "seen": 6, "select": [10, 11, 12], "self": 6, "sens": [1, 6], "separ": [4, 6], "serv": [4, 6, 7], "set": [3, 4, 6, 7, 8, 10, 11, 13], "setup": [4, 6, 9, 12], "sever": [2, 6], "sh": [6, 8, 10, 11], "sha": 10, "shard": 10, "share": [2, 5, 6, 7, 10, 12], "shell": [6, 7, 8, 10, 11], "short": [2, 7], "should": [6, 7, 8, 10, 11, 12], "show": [2, 7, 8, 12], "shown": 11, "shylu": 10, "side": [1, 11], "sigsegv": 2, "similar": [4, 7, 8], "simpl": [7, 10, 12], "simple_views_1d": 10, "simple_views_2d": 10, "simplest": 12, "simpli": [3, 6, 7, 8, 10, 11, 12], "simplifi": 10, "sinc": [1, 7, 8, 10, 11, 12], "singl": [6, 7], "singular": 2, "situat": 2, "size": 4, "skylak": 2, "skylake_avx512": 10, "slack": 6, "slightli": 1, "slurm": 10, "sm": 6, "small": [4, 6, 12], "smaller": 12, "snapshot": [4, 5, 9, 11, 14], "snl": 5, "so": [1, 2, 6, 7, 8, 10, 11, 12], "softar": 9, "softwar": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13], "softwwar": 12, "solv": [2, 7, 10, 11], "some": [1, 4, 6, 7, 10, 12], "someth": [6, 10, 12], "sometim": 6, "sort": [7, 12], "sought": 1, "sourc": [2, 6, 7, 9, 10, 11], "source_cach": 12, "sp3klcm": 10, "sp3klcmwurgk2hrye2tpgjv5x2pq3tlq": 10, "space": [3, 4, 9, 10], "spack": [0, 5, 9, 10, 13, 14], "spack_download": 12, "spack_manag": [5, 6, 8, 10, 11], "spacktiv": 2, "span": 3, "spark": 1, "spars": 10, "spawn": 8, "spec": [0, 4, 8, 9, 10, 11, 12], "specif": [2, 4, 6, 7, 8, 10, 13], "specifi": [2, 6, 7, 8, 10, 12], "specifii": 11, "sqlite3": 2, "src": 10, "stabl": 6, "stack": [1, 8, 11], "stage": [2, 7, 8, 12], "stai": 6, "stale": 6, "stamp": [4, 5, 8], "stand": 2, "standard": [7, 8, 11], "start": [4, 6, 7, 9, 10, 11, 14], "state": [2, 6], "static": 2, "statu": 8, "step": [4, 6, 8, 9, 10, 11, 12], "still": [1, 3, 6, 10, 12], "stitch": 4, "stk": 10, "stk_unit_test": 10, "stl": 2, "stokho": 10, "stop": [7, 11], "storag": [6, 8], "store": [5, 8, 12], "straightforward": 2, "strategi": [1, 2, 4, 9, 12], "stratimiko": 10, "streamlin": 4, "string": [2, 12], "strive": 1, "structur": [0, 4], "strumpack": 10, "sub": [8, 11], "subcommand": 2, "submodul": [6, 7, 10, 12], "subshel": [8, 11], "success": 11, "successfulli": 10, "succint": 2, "suffici": 7, "suggest": [6, 12], "suit": 10, "summar": [2, 10], "superlu": [2, 10], "suppli": [4, 11, 12], "support": [3, 4, 6, 7, 8, 12], "sure": 6, "switch": [1, 6, 10], "sy": 12, "symbol": 7, "symlink": 2, "syntax": [6, 7], "system": [2, 3, 4, 5, 7, 8, 12, 14], "szip": 2, "t": [6, 7, 8, 10, 11], "tabl": 8, "tag": 7, "take": [7, 10, 11, 12], "tar": 7, "target": [1, 8], "task": 10, "team": [1, 3, 4, 12], "techniqu": 12, "tediou": 6, "teko": 10, "tell": [3, 6, 7, 10], "tempu": 10, "tenant": 1, "term": [6, 12], "termin": 8, "termlib": 2, "tesla": 10, "test": [2, 4, 6, 7, 9, 10, 11, 12], "text": 6, "than": 8, "thei": [2, 6, 7, 8, 10, 11, 12], "them": [2, 3, 4, 6, 7, 8, 11, 12], "themselv": 7, "therefor": 2, "thi": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13], "thin": 4, "thing": [1, 2, 6, 7, 8, 11], "think": 7, "thorough": 7, "those": [8, 11], "though": 6, "thought": 4, "thousand": 4, "thread": 2, "thread_multipl": 2, "threadsaf": 2, "three": [4, 8], "through": [1, 2, 4, 5, 7, 10], "thu": 2, "tidi": 7, "time": [2, 4, 5, 6, 7, 8, 12], "timestamp": 11, "tioga": 10, "tip": 6, "tmp": 12, "togeth": [1, 4, 7], "too": 8, "tool": [1, 2, 4, 6, 7, 12], "top": [1, 7, 12], "topic": [4, 9, 14], "total": 10, "toward": 1, "tpetra": 10, "tpl": 1, "track": 10, "trade": 6, "transit": 12, "translat": 10, "treat": 7, "tree": [6, 12], "tri": [6, 7], "trial": 1, "trick": [6, 12], "trigger": 8, "trilino": [7, 10], "trilinoscoupl": 10, "trivial": 7, "true": [6, 12], "truli": 6, "try": [4, 6], "turn": [6, 7, 10], "tutori": [7, 8, 10, 11], "tweak": 12, "two": [2, 6, 7, 11, 12], "txt": [10, 11], "type": [3, 4, 6, 7, 11], "typic": [2, 3, 4, 5, 7, 8, 10, 12], "u": [2, 10], "ukbdvp": 10, "ukbdvpe47x3frgurzhknhbfoq4iskfv3": 10, "unaccept": 8, "under": 12, "undergo": 2, "understand": [2, 7, 9], "understood": 7, "unfamiliar": 8, "unif": 6, "unifi": [2, 6, 10, 12], "uniformli": 12, "uninstal": [2, 6], "uniqu": 6, "unit": [2, 6, 7, 10], "unit_test": 10, "unittestx": [6, 10], "unless": [7, 10, 11], "unneccesari": 11, "unnecessari": 7, "unpack": 10, "unsupport": 10, "up": [4, 8, 9, 10, 11, 13], "updat": [2, 6, 8, 10, 11, 12], "update_golds_10_26_2021": 10, "upgrad": 10, "upon": 11, "upstream": [6, 8, 10], "url": 7, "us": [1, 2, 4, 5, 7, 8, 9, 10, 12, 13, 14], "usag": [3, 7, 8], "user": [0, 1, 2, 6, 8, 10, 12, 13], "usual": 7, "util": [2, 4, 7, 9, 10, 12], "uyq6mxb": 10, "uyq6mxbuc2lw3oext626lbmyiiyh7bqf": 10, "v": 10, "v0": 10, "v1": 10, "v100": 10, "valid": 11, "valu": [7, 12], "variabl": [5, 6, 8, 12], "variant": [2, 6, 7, 12], "variat": 3, "variou": 4, "ve": [6, 7, 11], "vendor": 4, "veri": [2, 6, 7], "verifi": 10, "version": [2, 4, 7, 8, 10, 11, 13], "via": [7, 12], "view": [6, 10, 11, 12], "vim": 6, "virtual": 7, "vt": 2, "vv": [6, 8], "wa": [1, 2, 7, 8, 10, 11, 12], "wai": [3, 4, 6, 7, 8, 12], "wait": 6, "walk": 7, "want": [5, 6, 7, 8, 10, 11, 12], "warn": [8, 10, 11], "wasn": 11, "we": [1, 2, 4, 6, 7, 8, 10, 11, 12], "weight": 4, "well": [2, 4, 8, 10], "were": 1, "what": [2, 4, 9, 11, 14], "when": [2, 3, 4, 7, 8, 9, 11, 12], "whenev": [6, 7, 11], "where": [2, 6, 7, 8, 10, 11, 12], "which": [1, 2, 7, 8, 10, 11], "while": [1, 2, 3, 6, 10], "who": [5, 7, 11, 13], "whole": [7, 12], "whose": 11, "wide": 12, "wind": [2, 5, 6, 7, 8, 10, 11], "wish": [4, 6, 7, 8, 10, 11, 12], "within": [2, 10, 12], "without": [2, 6, 8, 10, 11], "won": 7, "word": 11, "work": [0, 1, 3, 6, 7, 8, 11, 12], "workflow": [1, 4, 6, 7, 9, 11, 14], "worri": 6, "would": [2, 6, 7, 8, 12], "wrap": 7, "wrapper": [2, 4, 10], "write": [4, 9], "x": 8, "x11": 10, "x86_64": 2, "xbla": [2, 10], "xz": 2, "y": [2, 6, 8], "yaml": [2, 3, 6, 7, 8, 10, 11, 12], "you": [4, 5, 6, 8, 9, 10, 11, 14], "youe": 11, "your": [2, 5, 6, 7, 8, 10, 11], "ypwgjj2": 10, "ypwgjj2akokavha4jkpqm4prylh2vmjr": 10, "zero": 4, "zlib": 2, "zoltan": 10, "zoltan2": 10}, "titles": ["General Information", "History and inspirations for Spack-Manager", "Important Spack Features", "Spack-Manager Structure", "Spack-Manager", "Analysts Documentation", "Advanced Topics for Developers", "Developers: What you need to know about Spack", "Quick-Start: Developer Workflow", "Developer Documentation", "Snapshot Developer Workflow Example", "Useful Commands for Development", "Creating and configuring a Spack-Manager Project", "System Administrator Documentation", "User Profiles"], "titleterms": {"about": 7, "activ": 11, "ad": 12, "administr": 13, "advanc": 6, "an": [6, 8], "analyst": 5, "anonym": 12, "auto": 12, "back": 8, "benefit": 4, "build": [6, 7, 8, 10, 11], "chang": 8, "clean": 6, "code": [8, 10], "come": 8, "command": [2, 7, 11], "configur": 12, "conserv": 6, "construct": 6, "control": 12, "creat": [8, 11, 12], "debug": 6, "detect": 12, "dev": 11, "develop": [6, 7, 8, 9, 10, 11], "disk": 6, "dive": 11, "document": [5, 9, 13], "edit": 10, "env": 11, "environ": [6, 8, 11], "error": 6, "exampl": 10, "featur": 2, "from": 12, "gener": 0, "handl": 6, "histori": 1, "how": 6, "import": 2, "inform": 0, "inspir": 1, "instanc": 6, "iter": 10, "know": 7, "knowledgebas": 2, "load": 11, "machin": 12, "major": 7, "make": 8, "manag": [1, 3, 4, 6, 8, 12], "modifi": 6, "multipl": 6, "need": 7, "old": 6, "other": 11, "packag": 12, "popul": 12, "process": [7, 11], "profil": [4, 14], "project": 12, "prompt": 11, "queri": 7, "quick": [8, 11], "re": 11, "read": 7, "remov": 11, "repositori": 12, "run": [8, 10], "scratch": 12, "set": 12, "setup": [8, 10, 11], "snapshot": 10, "sourc": 8, "space": 6, "spack": [1, 2, 3, 4, 6, 7, 8, 11, 12], "spec": [2, 6, 7], "specif": 12, "start": 8, "step": 7, "strategi": 6, "structur": 3, "system": 13, "test": 8, "topic": 6, "up": [6, 12], "us": [6, 11], "user": [4, 14], "util": 6, "version": 12, "what": 7, "when": 6, "workflow": [8, 10], "write": 7, "you": 7}}) \ No newline at end of file diff --git a/user_profiles/analysts/analysts.html b/user_profiles/analysts/analysts.html new file mode 100644 index 00000000..7b7bcc52 --- /dev/null +++ b/user_profiles/analysts/analysts.html @@ -0,0 +1,143 @@ + + + + + + + + + Analysts Documentation — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Analysts Documentation

+

This documentation is for people who just want to run the software on preconfigured machines.

+

Spack-Manager deploys software through modules. The Spack-Manager infrastructure is designed to create time-stamped snapshots. Typically this will be done by system-administrators, but anyone building software can create snapshot modules or custom modules that can be shared.

+

To use modules you need to add the location of the module files to your MODULEPATH environment variable. These are typically stored in the $SPACK_MANAGER/modules directory. You can execute the command

+
module use [path/to/modules]
+
+
+

to add the Spack generated modules to the list of available modules in your environment.

+

The location of these module files on the major machines are:

+ + + + + + + + + + + + + + + + + +

Machine Name

Path

snl-hpc

/projects/wind/spack-manager/modules

cee

/projects/wind/spack-manager/modules

eagle

/projects/exawind/exawind-snapshots/modules

+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/user_profiles/developers/advanced_topics.html b/user_profiles/developers/advanced_topics.html new file mode 100644 index 00000000..cefb2cdc --- /dev/null +++ b/user_profiles/developers/advanced_topics.html @@ -0,0 +1,332 @@ + + + + + + + + + Advanced Topics for Developers — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Advanced Topics for Developers

+

This section is designed to go over some of the tips and tricks for developers +that will help you improve your workflow and handle some more nuanced scenarios.

+
+

Handling Multiple Environments

+

Spack-Manager is designed to support multiple environments from a single Spack +instance. +This allows common libraries to be reused between installations. +Where you place the environments is entirely up to you. +There is a default location $SPACK_MANAGER/environments where the environments +will be created if you pass the --name or -n flag into one of the environment +creation commands. +Using the --directory or -d argument will create the environment at the local +path you specify. +Omitting either of these arguments will lead to the environment being created in +the current working directory.

+

In terms of when to create an environment, our recommendation is that an environment +be created for each unique concept you are working on, and once that concept is finalized +you uninstall the software and/or delete the environment.

+
+
+

Cleaning Up Old Environments

+

If an environment is stale and hasn’t been used in a while, our recommendation +is to create a new environment using it’s spack.yaml and then just delete the +old environment.

+

An example of how to do this is:

+
quick-create -d [location of new env] -y [old environment]/spack.yaml
+spack -e [old environment] uninstall --all
+rm -rf [old environment]
+
+
+
+

TIP: Using spack -e [env location] allows you to run commands in that environment +without activating it in your shell.

+
+

If you truly wish to revise the environment then it is a good idea to try and reconcretize +before making changes to the environment. spack concretize -f.

+
+
+

Modifying Specs in an Environment

+

Once an environment is active in your shell it can still be modified. +The definition of the environment is in the spack.yaml file and modifying this +will modify the environment. +So to add a variant, such as making the build a debug build, simply open the spack.yaml +in your environment’s directory and add build_type=Debug to the spec for the package +you want to be built in debug mode.

+
+

TIP: Spack has a built in command for automatically opening the spack.yaml file in a +text editor for you. It is spack config edit. The default editor is Vim, but you can set it to be anything you want simply by setting the EDITOR environment variable i.e. export EDITOR=emacs.

+
+

A more archaic way to do this from the command line would be to remove the spec +and then add it back with the edits that you want.

+

For example say you have amr-wind@master+openfast+hypre as the spec in your environment. +You could run

+
spack rm amr-wind@master
+spack add amr-wind@master+openfast+hypre build_type=Debug
+
+
+

if you really don’t want to open the yaml file. +This is discouraged though because it involves more typing and is prone to more errors. +All users are encouraged to become comfortable reading and editing the spack.yaml file. +The ones generated by Spack-Manager are quite small and only contain information pertinent +to you as an end user.

+
+
+

Debugging Spack Errors

+

It is inevitable that you will encounter some error from Spack while using Spack-Manager. +Spack-Manager is a dynamic tool that tries to stay up-to-date with Spack’s new features. +Sometimes we catch bugs and sometimes there are incompatibilities or inconsistencies +in the state of your Spack installation.

+

We suggest the following steps for how to handle an error from Spack:

+
    +

  1. If you just updated Spack-Manager make sure the Spack submodule is up-to-date: git submodule update

    2. +

  2. Read the error message again and see if it makes sense. Many of the error messages are quite good.

    3. +

  3. Run sm-clean. This is a heavy clean up command for Spack-Manager that we’ve created based on the errors we’ve seen in the past.

    4. +

  4. Run your Spack command with the -d flag (debug) i.e. spack -d install and see if that gives you any more insight

    5. +

  5. Reach out for help on slack, github issues or email.

    6. +
+
+
+

When and How to Use Multiple Instances of Spack-Manager

+

Sometimes it is useful to have multiple instances of Spack-Manager. +Some examples of when it would be a good idea to do this:

+
    +

  • You have multiple machines on a shared filesystem and they are conflicting, or one is problematic while the other is stable.

    • +

  • You want to archive production environments/builds and separate them from your software development work.

    • +

  • You are developing features for Spack or Spack-Manager and want to keep it separate from the rest of your work.

    • +
+

The key concept here is that there is something stable and something more dynamic. +It is useful to blow away everything in dynamic software development and start from scratch periodically.

+

Spack-Manager has been designed to be self-contained and to not create or use dependencies from other Spack +instances as much as possible. +The key thing is you don’t want to mix Spack instances in the same shell. +So to use different Spack-Manager instances you just need to make sure that the SPACK_MANAGER environment variable +is set to the right instance and that you don’t switch things up in the same shell.

+

An example of how this can be done in a bashrc is:

+
# Load dynamic spack-manager for software development
+function development-spack-manager(){
+  export SPACK_MANAGER=/path/to/my/dynamic/spack-manager
+  source ${SPACK_MANAGER}/start.sh
+  spack-start
+}
+
+# Load stable builds
+function production-spack-manager(){
+  export SPACK_MANAGER=/path/to/my/production/spack-manager
+  source ${SPACK_MANAGER}/start.sh
+  spack-start
+}
+
+
+

In this example the different Spack-Manager instances can be loaded in a new shell by calling separate functions.

+
+
+

Strategies for Conserving Disk Space

+

If Spack is not periodically pruned it can become a storage hog. +When doing software development Spack will create and preserve the build directory for develop specs, +and then it will install the binaries in the common Spack install tree.

+

To prune your local build directories you can simply run rm -rf spack* inside a build directory. +This will remove all the files and directories Spack created but not modify your source code. +It is essentially just removing the CMake build directory and all of Spack’s logs. +If you are frequently modifying specs for your environment (switch from Release to Debug) then you +will notice several build directories spack-build-[hash]. +Preserving these allows for incremental builds, and deleting them will cause you to rebuild the entire software product. +So there is a trade off between waiting on builds and storage space.

+

To handle the issue of install trees we’ve added the --local-source or -l flag to the environment creation commands. +This will make it so all the binaries are installed local to the environment in a directory named opt/. +Now when you delete the environment you will also delete all the install binaries and you don’t need to worry about them piling up in the +main Spack install tree.

+

However, if you only use this option you will end up rebuilding all the binaries in every environment. +Using --local-source means that the environment can’t doesn’t see any of the other environments and you will need to create a link between them. +To link to your main Spack database create the $SPACK_MANAGER/configs/user/upstreams.yaml file and put the following inside of it:

+
upstreams:
+ root_spack:
+   install_tree: $spack/opt/spack
+
+
+

Any files added to the $SPACK_MANAGER/configs/user directory will automatically be added to the environments you create going forward. +This allows users to set configurations like upstreams or personal preferences without needing to have them get pushed to the main repo. +The addition above makes it so any --local-source environment you create can reuse binaries from your main install tree.

+

So to setup a very space conservative Spack-Manager repo you should do the following:

+
    +

  1. Create a base environment and install the software you want to use without using --local-source

    2. +

  2. Create the upstreams.yaml file as specified above.

    3. +

  3. Create all development environments with the --local-source or -l flag.

    4. +
+

Now whenever you want to clean things up just delete your development environment directory and all the space from that specific build will be removed. +Doing this is a bit tedious and the new base environments will need to be periodically created for new compilers and flags, or the existing ones will need to be updated.

+
+
+

Constructing and Utilizing Multiple builds

+

One of the nice features about using Spack is the build environments you setup can have arbitrary complexity. +A nice feature for this is to setup your development environment to perform multiple builds that you may need +from the same source such as a +cuda and ~cuda build, or Release and Debug builds.

+

To do this you need to edit the spack.yaml file so that the concretizer:unify parameter is set to false. +Unify tells the concretizer that all the software has to concretize into a single graph. +We turn on unification by default in Spack-Manager to serve as a guard-rail for users and to simply syntax for setting up environments.

+
spack:
+  # having the two specs
+  specs: 
+  - nalu-wind@master+hypre+cuda
+  - nalu-wind@master+hypre~cuda
+  view: false
+  concretizer:
+    unify: false # this is defaulted to true
+  include:
+  - include.yaml
+  develop:
+    nalu-wind:
+      # this develop spec matches both the root specs and so the source code will be used for both
+      spec: nalu-wind@master
+
+
+

You may not want to rebuild both instances of the code every time you make a change. +However, you can do build-env-dive nalu-wind~cuda if you want to develop the code on a non-cuda environment for the faster link times. +When using build-env-dive you can simply call make, make clean, run the tests, etc from inside the build directory. +When you want to test the cuda build you can exit the build-env and rebuild the Cuda case. +An example of this workflow is illustrated below.

+
# Setup the environment
+quick-create -d two-build-one-env -s nalu-wind+cuda nalu-wind~cuda
+spack manager develop nalu-wind@master
+spack config add conncretizer:unify:false # a way to edit the spack.yaml configs from the command line
+spack install 
+# dive into the non-cuda build environment
+build-env-dive nalu-wind~cuda
+# make some code changes
+[...]
+# run the unit-tests and interate
+make -j8 && ./unittestX
+# jump out of the build0-env 
+exit
+# now rebuild everything with the changes
+spack install
+# check the cuda tests
+build-env-dive nalu-wind+cuda
+ctest -R unit -VV
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/user_profiles/developers/developer_spack_minimum.html b/user_profiles/developers/developer_spack_minimum.html new file mode 100644 index 00000000..62ece4a6 --- /dev/null +++ b/user_profiles/developers/developer_spack_minimum.html @@ -0,0 +1,340 @@ + + + + + + + + + Developers: What you need to know about Spack — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Developers: What you need to know about Spack

+

Developers who are using Spack-Manager as their build system need to know some basic things about Spack +to effectively utilize the tool. +We’ve tried to minimize the required knowledge you need to retain for commands, but it is important to +understand the fundamental concepts of Spack to obtain autonomy in your basic workflow and communicate +effectively when looking for help.

+

The most critical concepts to learn for development are:

+
    +

  1. Querying the Spack commands: spack info and --help

    2. +

  2. Reading and writing Spack specs

    3. +

  3. The major steps of the Spack build process

    4. +
+
+

Querying the Spack commands

+

The first item in this list is also arguably the most important. +A large array of questions about Spack can be answered by simply using the -h or --help flags +for the commands. Every Spack command has this feature and this will print a short +description of the what the command does along with all the options the command takes. +For example:

+
spack cd -h
+usage: spack cd [-h] [-m | -r | -i | -p | -P | -s | -S | --source-dir | -b | -e [name]] ...
+
+cd to spack directories in the shell
+
+positional arguments:
+  spec                  package spec
+
+optional arguments:
+  --source-dir          source directory for a spec (requires it to be staged first)
+  -P, --packages        top-level packages directory for Spack
+  -S, --stages          top level stage directory
+  -b, --build-dir       build directory for a spec (requires it to be staged first)
+  -e [name], --env [name]
+                        location of the named or current environment
+  -h, --help            show this help message and exit
+  -i, --install-dir     install prefix for spec (spec need not be installed)
+  -m, --module-dir      spack python module directory
+  -p, --package-dir     directory enclosing a spec's package.py file
+  -r, --spack-root      spack installation root
+  -s, --stage-dir       stage directory for a spec
+
+
+

Prints all the information you need to know about how to use the command spack cd.

+

Spack-Manager has emulated this behavior by adding the -h/--help flags to all of the commands including shell commands. +So if you see a command you don’t understand, or if you ever forget the syntax for a command, the first starting point is the -h flag.

+

Along with the -h command, the other querying command that every developer should know is spack info. +spack info [package name] gives you all the information for a spec. Specifically for developers, this will tell you the versions and variants in the queried package.

+

For example spack info amr-wind gives:

+
spack info amr-wind
+CMakePackage:   amr-wind
+
+Description:
+    None
+Homepage: https://github.com/Exawind/amr-wind
+
+Maintainers: @jrood-nrel @michaeljbrazell
+
+Externally Detectable: 
+    False
+
+Tags: 
+    ecp  ecp-apps
+
+Preferred version:  
+    main    [git] https://github.com/Exawind/amr-wind.git on branch main
+
+Safe versions:  
+    main    [git] https://github.com/Exawind/amr-wind.git on branch main
+
+Deprecated versions:  
+    None
+
+Variants:
+    Name [Default]                 When       Allowed values          Description
+    ===========================    =======    ====================    ==================================
+
+    amdgpu_target [none]           +rocm      none, gfx1011,          AMD GPU architecture
+                                              gfx906, gfx802,         
+                                              gfx701, gfx803,         
+                                              gfx1010, gfx900,        
+                                              gfx801, gfx1012,        
+                                              gfx908, gfx90a          
+    asan [off]                     --         on, off                 Turn on address sanitizer
+    build_type [RelWithDebInfo]    --         Debug, Release,         CMake build type
+                                              RelWithDebInfo,         
+                                              MinSizeRel              
+    clangtidy [off]                --         on, off                 Turn on clang-tidy
+    cppcheck [off]                 --         on, off                 Turn on cppcheck
+    cuda [off]                     --         on, off                 Build with CUDA
+    cuda_arch [none]               +cuda      none, 32, 35, 10,       CUDA architecture
+                                              86, 72, 62, 61, 70,     
+                                              21, 50, 11, 12, 37,     
+                                              52, 30, 75, 53, 60,     
+                                              20, 13, 80              
+    hypre [on]                     --         on, off                 Enable Hypre integration
+    internal-amrex [on]            --         on, off                 Use AMRex submodule to build
+    ipo [off]                      --         on, off                 CMake interprocedural optimization
+    masa [off]                     --         on, off                 Enable MASA integration
+    mpi [on]                       --         on, off                 Enable MPI support
+    netcdf [on]                    --         on, off                 Enable NetCDF support
+    openfast [off]                 --         on, off                 Enable OpenFAST integration
+    openmp [off]                   --         on, off                 Enable OpenMP for CPU builds
+    rocm [off]                     --         on, off                 Enable ROCm support
+    shared [on]                    --         on, off                 Build shared libraries
+    tests [on]                     --         on, off                 Activate regression tests
+    unit [on]                      --         on, off                 Build unit tests
+
+Installation Phases:
+    cmake    build    install
+
+Build Dependencies:
+    amrex  cmake  cuda  hip  hsa-rocr-dev  hypre  llvm-amdgpu  masa  mpi  netcdf-c  openfast  py-matplotlib  py-pandas
+
+Link Dependencies:
+    amrex  cuda  hip  hsa-rocr-dev  hypre  llvm-amdgpu  masa  mpi  netcdf-c  openfast  py-matplotlib  py-pandas
+
+Run Dependencies:
+    None
+
+Virtual Packages: 
+    None
+
+
+

So if you want to know how to create a debug build, you can look at this information and see:

+
build_type [RelWithDebInfo]    --         Debug, Release,         CMake build type
+                                          RelWithDebInfo,         
+                                          MinSizeRel                
+
+
+

This is an list spec and the available options are listed. +So adding build_type=Debug to the spec i.e. amr-wind build_type=Debug will create a debug build. +If you want to turn on masa, you can add +masa. +This will be covered in more detail in the next section when specs are discussed. +For this section it is sufficient to know that spack info is the key to knowing what you need to write to customize your builds.

+
+
+

Reading and writing Spack specs

+

Spack specs are critical to using Spack-Manager because they are the language used to communicate the options and configurations of +the software that is getting built.
+We provide an overview of what a spec is, and the parts that go into making a Spack spec in our +general documentation, +and an even more thorough description can be found in the +spack documentation

+

A simple description of a spec for this section can be understood by looking at delimiters in a spec: {name}@{version}%{compiler}{variants} ^{dependent specs}.

+
    +

  • name is the package name. This is what you query with the spack info and is typically the name of the software.

    • +

  • version is what immediately follows the @ symbol. This can be aligned to a github branch, tag, or a url (i.e. download a tar file). The details for the versions can be found via the spack info command

    • +

  • compiler specification is what immediately follows the % symbol, and typically also has a name and version i.e. gcc@9.3.0

    • +

  • variants are the flags for the software. They can be booleans (where + is on and ~ is off) and lists i.e build_type=Release or cuda_arch=70

    • +

  • dependent specs are the ways to specify flags for the dependencies. Whenever a ^ is added it is delimiting to a new spec with the restriction that must be in the dependency graph of the first spec or root spec.

    • +
+

We don’t recommend developers use the ^ command at all since it makes things more confusing, and is unnecessary for normal development cycles. +It is addressed here for clarity and completeness, but you won’t need them unless you intend to build multiple version of the same software in the same environment. +An example of this would be an environment that builds the same software with multiple compilers, but this is typically a feature for system administrators, not standard development cycles.

+
+
+

Major steps of the Spack build process

+

Spack-Manager uses Spack environments to manage your development builds. +These environments are similar to Conda environments in concept, but they benefit from re-using software that you’ve built in previous environments. +As such it is recommended that you maintain a single instance of Spack-Manager to organize and curate your builds, and create new environments when you want to start a new development project. For example if you are working on multiple features at the same time it is convenient to maintain multiple environments.

+

Understanding the steps that go into creating an environment is helpful for debugging and thinking about how to organize your workflow. +Spack and Spack-Manager are also relatively easy to script in either bash or python, +but it is important to understand the build process to write effective scripts.

+

The major steps and associated commands for building software with Spack environments are (don’t forget to query the commands to learn more about them):

+
    +

  1. Create the environment: (spack manager create-env)
    +This generates a spack.yaml file which is how the environment is defined. Most of the following commands will be manipulating this file.

    2. +

  2. Activate the environment: (spack env activate)
    +This sets the environment as active in your shell.

    3. +

  3. Add root specs: (spack add)
    +Define the software that you want in the environment. Spack will solve for the dependencies of all these root specs, and ensure that your environment meshes together. They just need the name as a minimum.

    4. +

  4. Add develop specs (spack develop)
    +Determine what software you want to modify i.e. which specs you want to develop. +These specs must have the name and version as a minimum. +They are not going to be added to your environment by themselves, but rather serve as keys for the concretizer to determine if a spec should be treated as a develop spec or not. +Essentially, if the concretizer can determine that a spec in the graph can be equivalenced with the develop spec, then it will use your source code and not spack’s usual process for cloning/building/installing. +Think of this as a sort of dictionary. +For instance spack add trilinos and spack develop trilinos@develop will mean that trilinos will use the source code, +but if you had done spack add trilinos@master then it would not because trilinos@develop and trilinos@master can’t be equivalenced. +It is recommended that you always just do name@version for your develop specs to get the broadest match possible. +More documentation on this can be found in the spack documentation.

    5. +

  5. Concretize: (spack concretize)
    +This is how the Spack determines what the dependency graph needs to look like for your environment. It is a non-trivial problem to solve since you can use any combination of variants in each package in the DAG. Each software package can enforce built in conflicts that are set by the maintainers, but anything that is not constrained by your spec or the software itself will fall to the default (once again look to spack info to see the defaults).

    6. +

  6. Build/install: (spack install)
    +Now that you’ve decided what combination of software you want to build, what elements you want to develop, and what the dependency graph is all that is left is to build and install. Easy right?

    7. +
+

This may seem like a lot to go over, and this was not a very thorough description of each step. +These steps are covered with a workflow example in the developer tutorial +where we walk through each step one at a time. +The intention of this page is to serve as an introduction and a reference going forward. +If you forget a step or command you can always come back to this page to see what it is and see a brief description of the whole process. +It is also important to know that in your practical workflow you won’t need to type out each command every time you want to use Spack-Manager. +Spack-Manager contains convenience scripts that wrap the steps together, and print them as they execute to help you remember them.

+

The two most hands off commands are:

+
    +

  • quick-create-dev: this will do steps 1-5 for you automatically if you provide specs with versions in the input arguments (stops at step 4 if you don’t)

    • +

  • quick-activate: this will activate a previously created environment for you. You just pass the directory location to it.

    • +
+

For example, fastest way to start developing amr-wind and openfast together is:

+
quick-create-dev --name my-dev-project --spec amr-wind@main+openfast openfast@master
+# go to amr-wind source code
+spack cd amr-wind # modify the code in here as you wish
+# go to openfast source code
+spack cd openfast # modify the code in here as you wish
+# install code
+spack install
+
+
+

As a reminder, to learn more about the commnands used above quick-create-dev --help, spack cd --help, spack install --help. +To learn what other build options you have for amr-wind … spack info amr-wind, openfast … spack info openfast, etc.

+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/user_profiles/developers/developer_workflow.html b/user_profiles/developers/developer_workflow.html new file mode 100644 index 00000000..b3381f6d --- /dev/null +++ b/user_profiles/developers/developer_workflow.html @@ -0,0 +1,382 @@ + + + + + + + + + Quick-Start: Developer Workflow — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Quick-Start: Developer Workflow

+

In this section we will go over the developer work flow in Spack-Manager using the quick-functions.

+

This tutorial assumes you are familiar with the 3 things developers need to know. +If you are unfamiliar with these 3 things then please review the documentation before proceeding.

+

The developer workflow will be covered in 4 stages:

+
    +

  1. Setting up Spack-Manager

    2. +

  2. Create an environment for development

    3. +

  3. Building and making code changes

    4. +

  4. Running tests and coming back

    5. +
+

There is also the quick start below that just lists all the commands for you in a row.

+
+

Setup Spack-Manager

+

Setting up Spack-Manager should be a 1 time thing on a given machine. +First pick directory you want to store Spack-Manager. +The ideal location for this directory is one that has adequate storage for multiple build environments, +and it should also be on a filesytem that is accesible where you plan to run the software.

+
git clone --recursive git@github.com:sandialabs/spack-manager.git
+
+
+

For the purpose of this documentaiton we will define a SPACK_MANAGER environment variable, +and it should provide the absolute path to your Spack-Manager directory. +Spack-Manager also provides a spack manager location command which will provide an absolute path +to the Spack-Manager source directory. +To have access to the +commands we will use in this tutorial you need to source $SPACK_MANAGER/scripts/quick_commands.sh. +This script enables all the shell functions in Spack-Manager but it does not activate Spack. +We do this to allow you to add these lines to your bash_profile without any penalty +since sourcing Spack adds an unacceptable level of overhead for standard shell spawning,

+
# These lines can be added to your bash_profile
+export SPACK_MANAGER=$(pwd)/spack-manager
+source $SPACK_MANAGER/scripts/quick_commands.sh
+
+
+
+
+

Creating an Environment

+

With the Spack development workflow we are going to create an environment similar to a Conda environment. +Setting up the environments is a multistep process that is outlined in greater detail here and here. +There are three quick-commands for creating environments: quick-create, quick-create-dev and quick-develop. +They all exit the process of setting up an environment at different points in the process as outlined below:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Step

quick-create

quick-create-dev

quick-develop

Create an environment

x

x

x

Activate an environment

x

x

x

Add root specs

x

x

x

Add develop specs

x

x

Add externals

x

Concretize and install

+

For developers we recommend using quick-create-dev and quick-develop depending on if you want to use externals or not.

+

The interface for both of these commands is exactly the same. Moving forward we will use quick-create-dev in this example. +To see the options for the command we can run it with the --help command.

+
quick-create-dev -h
+*************************************************************
+HELP MESSAGE:
+quick-create-dev sets up a developer environment
+where all specs are develop specs that will be automatically cloned
+from the default repos
+    
+The next typical steps after running this command are to add externals if
+you want them, or run spack install.
+    
+The base command and it's help are echoed below:
+    
+
++ spack manager create-dev-env -h
+usage: spack manager create-dev-env [-h] [-m MACHINE] [-d DIRECTORY | -n NAME] [-y YAML] [-s SPEC [SPEC ...]]
+
+optional arguments:
+  -d DIRECTORY, --directory DIRECTORY
+                        Directory to copy files
+  -h, --help            show this help message and exit
+  -m MACHINE, --machine MACHINE
+                        Machine to match configs
+  -n NAME, --name NAME  Name of directory for environment (managed environment)
+  -s SPEC [SPEC ...], --spec SPEC [SPEC ...]
+                        Specs to populate the environment with
+  -y YAML, --yaml YAML  Reference spack.yaml to copy to directory
+*************************************************************
+
+
+

The main flags to use for standard developer workflow are the --name or --directory flags and the --spec flags.

+

To set up a build of the exawind driver where we are developing amr-wind and nalu-wind too we would run:

+
quick-create-dev -n example-env -s exawind@master nalu-wind@master amr-wind@main
+
+
+

If you don’t want to develop one of these packages (say you’re only focused on amr-wind) then just ommit the software you don’t +plan to develop in from the spec list in the command above. Please note that these specs need to be concrete specs, meaning they have the name +(amr-wind) and the version from spack (main), and that that the version is not necessarily the same thing as the branch. +This is covered in the things developers need to know about Spack for those needing a refresher.

+

The -n flag can be replaced with -d if we want to setup an environment in a different location than spack:config:environments_root (see the spack documentation for help on configuring custom managed spack environment locaitons). +The quick-create-dev command will execute all the stages in the table above including cloning the repos from github for the software. +These clones of the source code default to the environment directory you specified with the -d or -n flags. +If we wish to work off specific branches then we can use git add remote, git fetch and git checkout to get the branches we want +inside each of the clones before building.

+
+

Managing the Source Code

+

There are 4 options for setting up the source code you will use in your development process

+
    +

  1. Allow spack to clone the default git repo and branch when you use the spack develop or spack manager develop commands.

    2. +

  2. Use the spack manager develop command with the --repo-branch argument to clone from a specific fork and branch.

    3. +

  3. Pre-clone the source code into the environment directory.

    4. +

  4. Use additional develop arguments to point spack to exisiting source code outside the environment directory.

    5. +
+

Option 1 happens automatically if you run quick-create-dev. Option 2 can be used with an active environment. +See below for an example of how to use option2.

+
# create an environment and acticate it with "quick-create"
+# then clone the "amr-feature" branch from a user specific fork of the amr-wind git repo
+# then clone the "openfast-feature" branch from a user specific fork of the openfast git repo
+# finally build the software using the source code that was just cloned
+quick-create -n build-from-my-fork -s amr-wind+openfast
+spack manager develop --repo-branch git@github.com:psakievich/amr-wind.git amr-feature amr-wind@main
+spack manager develop --repo-branch git@github.com:psakievich/openfast.git openfast-feature openfast@master
+spack install
+
+
+

If you wish to pre-clone your repos using option 3 you can simply create a directory, +pre-clone the software you want to develop with names that match the package names and run your quick-create-dev inside the directory you created without either of the -d or -n flags. +This is because the default behavior of the command is to create the environment files, and clone repos in the current +working directory.

+

For example:

+
mkdir test && cd test
+# note that we name the clone of exawind-driver 'exawind' in the clone process to match the spack package name
+git clone --recursive --branch main git@github.com:Exawind/exawind-driver.git exawind
+git clone --recursive --branch master git@github.com:Exawind/nalu-wind.git
+git clone --recursive --branch main git@github.com:Exawind/amr-wind.git
+quick-create-dev -s exawind@main amr-wind@main nalu-wind@master
++ spack manager create-dev-env -s exawind@master amr-wind@main nalu-wind@master
+==> Configuring spec exawind@master for development at path exawind
+==> Warning: included configuration files should be updated manually [files=include.yaml]
+==> Configuring spec amr-wind@main for development at path amr-wind
+==> Configuring spec nalu-wind@master for development at path nalu-wind
++ spack env activate --dir /current/working/directory --prompt
+
+
+

does the same thing as

+
quick-create-dev -d test -s exawind@master nalu-wind@master amr-wind@main
+
+
+

However, adding in the extra pre-clone steps gives you a little more control over your environment.

+

Options 1 and 2 are the recommended ways of proceeding since they are the most concise and support the most common use cases. +Option 3 is available if you need additional flexibility, are on an air gaped system +or have issues with spack cloning from git (this may be due to an old version of git on the system). +Option 4 is not really recommended but the curious can learn more by diving into spack’s documentation and/or using spack manager develop --help +to learn the features and combinations available.

+

At this point in the process your environment is active and all setup. +You can confirm that it is active with spack env status which displays the active environment.

+
+
+
+

Building and Making Code Changes

+

Once the environment is setup and active you can simply run

+
spack install
+
+
+

to build the software.

+

In this case we are building without externals so you will see clingo get bootstrapped, concretization happen, and then the install occur for the entire software stack.

+

You are free to make code changes in any of the code directories. +Re-running spack install will cause Spack to check for changes by inspecting the time-date stamp on the files in the source code directories. +If they are newer than the install time then it will trigger an incremental build to capture any changes that might exist. +Any changes you make in a dependency will also trigger a rebuild of the upstream software too. +In this environment if you make a change in amr-wind it will also trigger a rebuild of the exawind package as well.

+

If you wish to just do a quick incremental build you can use the spack manager make command:

+
spack manager make amr-wind -j=16
+
+
+
+
+

Running Tests and Coming Back

+

To run tests in a one off manner you can use the spack build-env command to run commands in a sub-shell with the build environment. +This is further documented here. +We also have a function build-env-dive which is a beta feature that launches this same subshell in your terminal and dives into it. +It is further documented here. +Finally, if a test target is implementd for your software you can use spack manager make

+
spack manager make --args="test -j16" amr-wind
+
+
+

If you wish to come back to an environment later, or in a new shell you can just run

+
quick-activate /path/to/the/environment/you/wish/to/activate
+
+
+

and this will do all the activation for the environment for you. +You will be able to come back at anytime and pick up where you left off.

+
+
+

Quick Start

+

These are the commands needed to set up Spack-Manager and a development build for the exawind-driver with the intention of editing nalu-wind and amr-wind at the same time.

+
# setup Spack-Manager
+git clone --recursive git@github.com:sandialabs/spack-manager.git
+export SPACK_MANAGER=$(pwd)/spack-manager
+source $SPACK_MANAGER/start.sh
+# setup environment
+quick-create-dev -n demo -s exawind@master amr-wind@main nalu-wind@master
+# build code
+spack install
+# code changes in amr-wind
+spack cd amr-wind
+# .... make code changes
+# code changes in nalu-wind
+spack cd nalu-wind
+# ... make code changes
+# re-build
+spack install
+# go to build directory
+spack cd -b nalu-wind
+# run all the overset regression tests in nalu-wind
+spack build-env nalu-wind ctest -R overset
+# run regression tests in the exawind-driver
+build-env-dive exawind
+ctest -VV
+# don't forget you need to exit this build env subshell when you're done by calling `exit`
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/user_profiles/developers/developers.html b/user_profiles/developers/developers.html new file mode 100644 index 00000000..889d9ea0 --- /dev/null +++ b/user_profiles/developers/developers.html @@ -0,0 +1,185 @@ + + + + + + + + + Developer Documentation — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Developer Documentation

+

Developers in this section are softare developers for the projects that are using Spack-Manager. +This documentation is to help understand the basic requirements and workflow for developing software using Spack-Manager.

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/user_profiles/developers/snapshot_workflow.html b/user_profiles/developers/snapshot_workflow.html new file mode 100644 index 00000000..adbc7ca6 --- /dev/null +++ b/user_profiles/developers/snapshot_workflow.html @@ -0,0 +1,455 @@ + + + + + + + + + Snapshot Developer Workflow Example — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Snapshot Developer Workflow Example

+

WARNING: This documentation is fairly specific to ExaWind and has not been generalized for an arbitrary Spack-Manager project. +THe information is still useful. However, you may not translate directly or be able to follow along.

+

In this tutorial we will look at how to setup a developer workflow using snapshots if they are provided on your machine.

+
+

Setup

+

We use the Eagle machine at NREL for the example, and we choose to develop both the hypre and nalu-wind +projects for running on the GPU using CUDA. Starting from nothing, we first clone Spack-Manager:

+
[user@el1 ~]$ export SCRATCH=/scratch/${USER}
+[user@el1 ~]$ cd ${SCRATCH}
+[user@el1 user]$ git clone --recursive https://github.com/sandialabs/spack-manager.git
+Cloning into 'spack-manager'...
+remote: Enumerating objects: 2610, done.
+remote: Counting objects: 100% (2610/2610), done.
+remote: Compressing objects: 100% (1001/1001), done.
+remote: Total 2610 (delta 1345), reused 2476 (delta 1256), pack-reused 0
+Receiving objects: 100% (2610/2610), 426.10 KiB | 4.14 MiB/s, done.
+Resolving deltas: 100% (1345/1345), done.
+Submodule 'spack' (https://github.com/spack/spack) registered for path 'spack'
+Cloning into '/lustre/eaglefs/scratch/user/spack-manager/spack'...
+remote: Enumerating objects: 354065, done.
+remote: Total 354065 (delta 0), reused 0 (delta 0), pack-reused 354065
+Receiving objects: 100% (354065/354065), 155.14 MiB | 22.08 MiB/s, done.
+Resolving deltas: 100% (150589/150589), done.
+Submodule path 'spack': checked out '3576e5f3d6b34d8bc8c8c8f2749127ece1ce89be'
+
+
+

We then activate Spack-Manager:

+
[user@el1 user]$ export SPACK_MANAGER=${SCRATCH}/spack-manager && source ${SPACK_MANAGER}/start.sh && spack-start
+
+
+

Once Spack-Manager itself is activated, we create the Spack environment in which we will install and develop. +To do this we use the spack manager create-env command. +Our environment will be called exawind using the --name argument. We will choose to focus on building Nalu-Wind using the spec +nalu-wind@master+hypre+cuda  %gcc, which means, nalu-wind at the master branch, with hypre +enabled (+hypre), and CUDA (+cuda ), using the GCC compiler (%gcc, which without a version, selects the default compiler version).

+
[user@el1 user]$ spack manager create-env --name exawind --spec 'nalu-wind@master+hypre+cuda  %gcc'
+making /scratch/user/spack-manager/environments/exawind
+
+
+

Once the environment is created, we need to activate it:

+
[user@el1 user]$ spack env activate -d ${SPACK_MANAGER}/environments/exawind
+
+
+

Both of the previous steps can be combined into one with quick-create-env -n exawind -s 'nalu-wind@master+hypre+cuda %gcc'.

+

Next, we will turn nalu-wind and hypre into “develop specs” with a command that tells Spack we want to edit the code for these packages +locally and always rebuild with our local clones of the packages. We do this with the spack manager develop command:

+
[user@el1 user]$ spack manager develop nalu-wind@master; spack manager develop hypre@develop
+==> Configuring spec nalu-wind@master for development at path nalu-wind
+==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml]
+==> Configuring spec hypre@develop for development at path hypre
+==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml]
+
+
+

The develop command clones both of our packages into the ${SPACK_MANAGER}/environments/exawind directory. It is possible to specify other locations +of these package repos if they are already cloned by using the -p option for specifying a path. If we want to let Spack clone, we +can always switch our remotes and branches within the repos cloned by Spack by doing something like the following:

+
[user@el1 user]$ cd ${SPACK_MANAGER}/environments/exawind/nalu-wind
+[user@el1 nalu-wind]$ git remote -v
+origin	git@github.com:Exawind/nalu-wind.git (fetch)
+origin	git@github.com:Exawind/nalu-wind.git (push)
+[user@el1 nalu-wind]$ git remote add mine git@github.com:user-nrel/nalu-wind.git
+[user@el1 nalu-wind]$ git remote rm origin
+[user@el1 nalu-wind]$ git remote rename mine origin
+[user@el1 nalu-wind]$ git pull
+remote: Enumerating objects: 15, done.
+remote: Counting objects: 100% (14/14), done.
+remote: Compressing objects: 100% (4/4), done.
+remote: Total 15 (delta 10), reused 14 (delta 10), pack-reused 1
+Unpacking objects: 100% (15/15), 2.78 KiB | 237.00 KiB/s, done.
+From github.com:user-nrel/nalu-wind
+ * [new branch]        jroverf/NonTemplateNodalGradPOpenBC -> origin/jroverf/NonTemplateNodalGradPOpenBC
+ * [new branch]        master                              -> origin/master
+ * [new branch]        update_golds_10_26_2021             -> origin/update_golds_10_26_2021
+There is no tracking information for the current branch.
+Please specify which branch you want to merge with.
+See git-pull(1) for details.
+
+    git pull <remote> <branch>
+
+If you wish to set tracking information for this branch you can do so with:
+
+    git branch --set-upstream-to=origin/<branch> master
+
+[user@el1 nalu-wind]$ git branch --set-upstream-to=origin/master master
+Branch 'master' set up to track remote branch 'master' from 'origin'.
+[user@el1 nalu-wind]$ git pull
+Already up to date.
+[user@el1 nalu-wind]$ git checkout update_golds_10_26_2021
+
+Branch 'update_golds_10_26_2021' set up to track remote branch 'update_golds_10_26_2021' from 'origin'.
+Switched to a new branch 'update_golds_10_26_2021'
+[user@el1 nalu-wind]$ git branch
+  master
+* update_golds_10_26_2021
+
+
+

Next, we decide how to take advantage of the prebuilt snapshots on the machine. Here we use the spack manager external +command to specify a “view” in which we want to pull external packages into our environment. Snapshots are organized by date. +With the --latest flag, Spack-Manager will find the latest snapshot available on your machine automatically. Here we will use the latest snapshot +and one that is attributed to our GCC with CUDA configuration, called gcc-cuda. Views are typically organized by compiler, +e.g. intel, clang, gcc, and +gcc-cuda, etc. We will need to “blacklist” any packages we plan on developing locally, but this happens automatically for packages +we have already set as develop specs.

+
[user@el1 user]$ spack manager external --latest -v gcc-cuda
+==> Warning: included configuration files should be updated manually [files=include.yaml]
+
+
+
+
+

Building

+

Once our externals and git clones are configured, we have the necessary *.yaml files in our ${SPACK_MANAGER}/environments/exawind environment directory +to “concretize” and (re)install our entire project. The spack.yaml file in this directory is the main yaml file in which the +other yaml files are included. Concretizing is required to solve or map our loosely defined nalu-wind@master+hypre+cuda  %gcc spec into “concrete” parameters of our dependency graph (or DAG). The concrete DAG is exactly how Spack will fulfill the dependencies for your spec. We +concretize with the command (we almost always want to use the force with -f). It will likely complain about us using the “original” concretizer, but this will be fixed in the future:

+
[user@el1 user]$ spack concretize -f
+==> Warning: the original concretizer is currently being used.
+        Upgrade to "clingo" at your earliest convenience. The original concretizer will be removed from Spack starting at v0.18.0
+==> Concretized nalu-wind@master%gcc+cuda+hypre 
+ -   rbzxf3n  nalu-wind@master%gcc@9.3.0~asan~boost~catalyst+cuda~fftw+hypre~ipo~openfast+pic~rocm+tests~tioga~wind-utils abs_tol=1e-15 build_type=Release cuda_arch=70 cxxstd=14 dev_path=/scratch/user/spack-manager/environments/exawind/nalu-wind rel_tol=1e-12 arch=linux-centos7-skylake_avx512
+ -   b5pippu      ^cmake@3.22.1%gcc@9.3.0~doc+ncurses+openssl+ownlibs~qt build_type=Release arch=linux-centos7-skylake_avx512
+ -   cwar5vn      ^cuda@11.2.2%gcc@9.3.0~allow-unsupported-compilers~dev arch=linux-centos7-skylake_avx512
+ -   ukbdvpe      ^hypre@develop%gcc@9.3.0~complex+cuda~debug+fortran~gptune~int64~internal-superlu~mixedint+mpi~openmp+shared~superlu-dist+unified-memory cuda_arch=70 dev_path=/scratch/user/spack-manager/environments/exawind/hypre arch=linux-centos7-skylake_avx512
+ -   ypwgjj2          ^mpt@2.22%gcc@9.3.0 arch=linux-centos7-skylake_avx512
+ -   g4tc7v2          ^netlib-lapack@3.9.1%gcc@9.3.0~external-blas~ipo+lapacke+shared~xblas build_type=Release arch=linux-centos7-skylake_avx512
+ -   sp3klcm      ^kokkos-nvcc-wrapper@3.2.00%gcc@9.3.0+mpi arch=linux-centos7-skylake_avx512
+ -   5agjw2c      ^nccmp@1.9.0.1%gcc@9.3.0~ipo build_type=Release arch=linux-centos7-skylake_avx512
+ -   p2fnhpz      ^netcdf-c@4.7.4%gcc@9.3.0~dap~fsync~hdf4~jna+mpi+parallel-netcdf+pic+shared patches=2c88dfbd6d339a0336a43b14a65a1d1df995b853b645e4af612617612a642a53 arch=linux-centos7-skylake_avx512
+ -   uyq6mxb      ^trilinos@develop%gcc@9.3.0~adios2~amesos+amesos2~anasazi~aztec~basker+belos+boost~chaco~complex+cuda+cuda_rdc~debug~dtk~epetra~epetraext~epetraextbtf~epetraextexperimental~epetraextgraphreorderings+exodus+explicit_template_instantiation~float+fortran+gtest+hdf5~hypre~ifpack+ifpack2~intrepid~intrepid2~ipo~isorropia+kokkos~mesquite~minitensor~ml+mpi+muelu~mumps~nox~openmp~phalanx~piro~python~rocm~rol~rythmos~sacado~scorec+shards~shared~shylu+stk~stk_unit_tests~stokhos~stratimikos~strumpack~suite-sparse~superlu~superlu-dist~teko~tempus+tpetra~trilinoscouplings+wrapper~x11+zoltan+zoltan2 build_type=Release cuda_arch=70 cxxstd=14 dev_path=/projects/exawind/exawind-snapshots/spack-manager/environments/exawind/snapshots/eagle/2022-01-26/trilinos gotype=long patches=ffdad9a639ff490da5bd4f254e3a849b9dbf39cf7d28f8ed4419a05048846cf6 arch=linux-centos7-skylake_avx512
+ -   ci73hai      ^yaml-cpp@0.6.3%gcc@9.3.0~ipo+pic+shared~tests build_type=Release arch=linux-centos7-skylake_avx512
+
+==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml]
+
+
+

Once our environment is concretized, we don’t have to concretize again unless we change some configuration in the *.yaml files. +Concretization is also not explicity required for the next spack install command, but if any *.yaml files are changed, it is +recommended to spack concretize -f. +So now we are able to install our project with the simple command:

+
[user@el1 user]$ spack install
+==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml]
+==> Installing environment /scratch/user/spack-manager/environments/exawind
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external cmake-3.22.1-b5pippuk6fzbpysv24phtw4etslotbs6)
+[+] /nopt/nrel/ecom/hpacf/compilers/2020-07/spack/opt/spack/linux-centos7-skylake_avx512/gcc-8.4.0/cuda-11.2.2-5muy3vijyqputqmbdyzhltqot3fvwibu (external cuda-11.2.2-cwar5vnomowwdorf57nay6e7erladdby)
+==> mpt@2.22 : has external module in ['mpt/2.22', 'slurm']
+[+] /opt/hpe/hpc/mpt/mpt-2.22 (external mpt-2.22-ypwgjj2akokavha4jkpqm4prylh2vmjr)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netlib-lapack-3.9.1-g4tc7v27alixmh2ail3lud3iweclbf52)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external kokkos-nvcc-wrapper-3.2.00-sp3klcmwurgk2hrye2tpgjv5x2pq3tlq)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external nccmp-1.9.0.1-5agjw2cs2kprcw2xm5ffmrojfc7aknnz)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netcdf-c-4.7.4-p2fnhpzbpg7wtriqqsbudgtdwgtcrud3)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external trilinos-develop-uyq6mxbuc2lw3oext626lbmyiiyh7bqf)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external yaml-cpp-0.6.3-ci73hainzvjnag2ynsg7jxvaotnflzal)
+==> Installing hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3
+==> No binary for hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 found: installing from source
+==> No patches needed for hypre
+==> hypre: Executing phase: 'autoreconf'
+==> hypre: Executing phase: 'configure'
+==> hypre: Executing phase: 'build'
+==> hypre: Executing phase: 'install'
+==> hypre: Successfully installed hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3
+  Fetch: 0.00s.  Build: 4m 30.38s.  Total: 4m 30.38s.
+[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3
+==> Installing nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx
+==> No binary for nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx found: installing from source
+==> No patches needed for nalu-wind
+==> nalu-wind: Executing phase: 'cmake'
+==> nalu-wind: Executing phase: 'build'
+==> nalu-wind: Executing phase: 'install'
+==> nalu-wind: Successfully installed nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx
+  Fetch: 0.00s.  Build: 32m 27.59s.  Total: 32m 27.59s.
+[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx
+
+
+

We notice that both nalu-wind and hypre are being rebuilt, while the rest of the dependency graph is fullfilled through the externals defined from +the selected snapshot. Now that we have built and installed our first iteration of the development cycle. We can pursue editing of code +and iterate easily on a simplified build process.

+
+
+

Editing Code

+

We start by verifying our currently activated environment in Spack:

+
[user@el1 user]$ spack find
+==> In environment /scratch/user/spack-manager/environments/exawind
+==> Root specs
+-- no arch / gcc ------------------------------------------------
+nalu-wind@master%gcc +cuda+hypre 
+
+==> 9 installed packages
+-- linux-centos7-skylake_avx512 / gcc@9.3.0 ---------------------
+cuda@11.2.2  hypre@develop  mpt@2.22  nalu-wind@master  nccmp@1.9.0.1  netcdf-c@4.7.4  netlib-lapack@3.9.1  trilinos@develop  yaml-cpp@0.6.3
+
+
+

Next we will edit code in hypre:

+
[user@el1 user]$ cd ${SPACK_MANAGER}/environments/exawind/hypre
+[user@el1 hypre]$ echo "//" >> src/HYPRE_parcsr_mgr.c
+
+
+

Then we can simply rebuild and install the entire project by:

+
[user@el1 hypre]$ spack install
+==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml]
+==> Installing environment /scratch/user/spack-manager/environments/exawind
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external cmake-3.22.1-b5pippuk6fzbpysv24phtw4etslotbs6)
+[+] /nopt/nrel/ecom/hpacf/compilers/2020-07/spack/opt/spack/linux-centos7-skylake_avx512/gcc-8.4.0/cuda-11.2.2-5muy3vijyqputqmbdyzhltqot3fvwibu (external cuda-11.2.2-cwar5vnomowwdorf57nay6e7erladdby)
+==> mpt@2.22 : has external module in ['mpt/2.22', 'slurm']
+[+] /opt/hpe/hpc/mpt/mpt-2.22 (external mpt-2.22-ypwgjj2akokavha4jkpqm4prylh2vmjr)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netlib-lapack-3.9.1-g4tc7v27alixmh2ail3lud3iweclbf52)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external kokkos-nvcc-wrapper-3.2.00-sp3klcmwurgk2hrye2tpgjv5x2pq3tlq)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external nccmp-1.9.0.1-5agjw2cs2kprcw2xm5ffmrojfc7aknnz)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netcdf-c-4.7.4-p2fnhpzbpg7wtriqqsbudgtdwgtcrud3)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external trilinos-develop-uyq6mxbuc2lw3oext626lbmyiiyh7bqf)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external yaml-cpp-0.6.3-ci73hainzvjnag2ynsg7jxvaotnflzal)
+==> Installing hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3
+==> No binary for hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3 found: installing from source
+==> No patches needed for hypre
+==> hypre: Executing phase: 'autoreconf'
+==> hypre: Executing phase: 'configure'
+==> hypre: Executing phase: 'clean'
+==> hypre: Executing phase: 'build'
+==> hypre: Executing phase: 'install'
+==> hypre: Successfully installed hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3
+  Fetch: 0.00s.  Build: 4m 26.05s.  Total: 4m 26.05s.
+[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3
+==> Installing nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx
+==> No binary for nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx found: installing from source
+==> No patches needed for nalu-wind
+==> nalu-wind: Executing phase: 'cmake'
+==> nalu-wind: Executing phase: 'build'
+==> nalu-wind: Executing phase: 'install'
+==> nalu-wind: Successfully installed nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx
+  Fetch: 0.00s.  Build: 1m 33.13s.  Total: 1m 33.13s.
+[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx
+==> Warning: Module file /lustre/eaglefs/scratch/user/spack-manager/spack/share/spack/modules/linux-centos7-skylake_avx512/nalu-wind-master-gcc-9.3.0-rbzxf3n exists and will not be overwritten
+
+
+

Notice both hypre and nalu-wind are rebuilt. Since nalu-wind depends on hypre, it is rebuilt in order, and nalu-wind is relinked to hypre. +Spack also performed the make install step and the binaries are installed to regular Spack paths in ${SPACK_MANAGER}/spack/opt. So the binaries can be referenced from the installed directory or from the build directories in each project in ${SPACK_MANAGER}/environments/exawind.

+

Next we can edit code in nalu-wind as well, and rebuild the project:

+
[user@el1 hypre]$ cd ${SPACK_MANAGER}/environments/exawind/nalu-wind
+[user@el1 nalu-wind]$ echo "//" >> unit_tests.C
+[user@el1 nalu-wind]$ spack install
+==> Warning: included configuration files should be updated manually [files=externals.yaml, include.yaml]
+==> Installing environment /scratch/user/spack-manager/environments/exawind
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external cmake-3.22.1-b5pippuk6fzbpysv24phtw4etslotbs6)
+[+] /nopt/nrel/ecom/hpacf/compilers/2020-07/spack/opt/spack/linux-centos7-skylake_avx512/gcc-8.4.0/cuda-11.2.2-5muy3vijyqputqmbdyzhltqot3fvwibu (external cuda-11.2.2-cwar5vnomowwdorf57nay6e7erladdby)
+==> mpt@2.22 : has external module in ['mpt/2.22', 'slurm']
+[+] /opt/hpe/hpc/mpt/mpt-2.22 (external mpt-2.22-ypwgjj2akokavha4jkpqm4prylh2vmjr)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netlib-lapack-3.9.1-g4tc7v27alixmh2ail3lud3iweclbf52)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external kokkos-nvcc-wrapper-3.2.00-sp3klcmwurgk2hrye2tpgjv5x2pq3tlq)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external nccmp-1.9.0.1-5agjw2cs2kprcw2xm5ffmrojfc7aknnz)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external netcdf-c-4.7.4-p2fnhpzbpg7wtriqqsbudgtdwgtcrud3)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external trilinos-develop-uyq6mxbuc2lw3oext626lbmyiiyh7bqf)
+[+] /projects/exawind/exawind-snapshots/spack-manager/views/exawind/snapshots/eagle/2022-01-26/gcc-cuda (external yaml-cpp-0.6.3-ci73hainzvjnag2ynsg7jxvaotnflzal)
+[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/hypre-develop-ukbdvpe47x3frgurzhknhbfoq4iskfv3
+==> Installing nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx
+==> No binary for nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx found: installing from source
+==> No patches needed for nalu-wind
+==> nalu-wind: Executing phase: 'cmake'
+==> nalu-wind: Executing phase: 'build'
+==> nalu-wind: Executing phase: 'install'
+==> nalu-wind: Successfully installed nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx
+  Fetch: 0.00s.  Build: 1m 27.78s.  Total: 1m 27.78s.
+[+] /lustre/eaglefs/scratch/user/spack-manager/spack/opt/spack/linux-centos7-skylake_avx512/gcc-9.3.0/nalu-wind-master-rbzxf3nbmxodxvgvtq72n22glbd7wpdx
+==> Warning: Module file /lustre/eaglefs/scratch/user/spack-manager/spack/share/spack/modules/linux-centos7-skylake_avx512/nalu-wind-master-gcc-9.3.0-rbzxf3n exists and will not be overwritten
+
+
+

Notice since nothing has changed in hypre, only nalu-wind was necessary to rebuild. We can continue to edit code and iterate simply by using the spack install command to rebuild the entire project concisely.

+
+
+

Running

+

Lastly, to run the code we typically want to enter the build directory and run an executable using the environment in which it was built. +We do this by doing the following where we run the nalu-wind unit tests as an example. While on a compute node on the Eagle machine:

+
[user@r103u23 ~]$ spack cd -b nalu-wind
+[user@r103u23 spack-build-rbzxf3n]$ spack build-env nalu-wind ./unittestX 
+   Nalu-Wind Version: v1.2.0
+   Nalu-Wind GIT Commit SHA: e9142052b09d6a6ddecbe9b83dedd1f7b4588fac-DIRTY
+   Trilinos Version: 13.1-ga66bb9c6fa4
+
+[==========] Running 478 tests from 116 test suites.
+[----------] Global test environment set-up.
+[----------] 1 test from Basic
+[ RUN      ] Basic.CheckCoords1Elem
+[       OK ] Basic.CheckCoords1Elem (1 ms)
+[----------] 1 test from Basic (2 ms total)
+
+[----------] 5 tests from BasicKokkos
+[ RUN      ] BasicKokkos.discover_execution_space
+
+Kokkos::Cuda is available.
+Default execution space info: macro  KOKKOS_ENABLE_CUDA      : defined
+macro  CUDA_VERSION          = 11020 = version 11.2
+Kokkos::Cuda[ 0 ] Tesla V100-PCIE-16GB capability 7.0, Total Global Memory: 15.78 G, Shared Memory per Block: 48 K : Selected
+Kokkos::Cuda[ 1 ] Tesla V100-PCIE-16GB capability 7.0, Total Global Memory: 15.78 G, Shared Memory per Block: 48 K
+
+[       OK ] BasicKokkos.discover_execution_space (0 ms)
+[ RUN      ] BasicKokkos.simple_views_1D
+[       OK ] BasicKokkos.simple_views_1D (2 ms)
+[ RUN      ] BasicKokkos.simple_views_2D
+[       OK ] BasicKokkos.simple_views_2D (2 ms)
+[ RUN      ] BasicKokkos.parallel_for
+[       OK ] BasicKokkos.parallel_for (1 ms)
+
+
+

One can also obtain a bash shell with the package’s build environment for performing many tasks by doing:

+
spack cd -b nalu-wind
+bash -rcfile ../spack-build-env.txt
+
+
+
+
+

Iterating

+

After the initial setup overhead is in place. The process for iterating in the code development can be summarized as such:

+
[user@el1 user]$ export SPACK_MANAGER=${SCRATCH}/spack-manager && source ${SPACK_MANAGER}/start.sh && spack-start && spack env activate -d ${SPACK_MANAGER}/environments/exawind
+[user@el1 user]$ #edit code
+[user@el1 user]$ spack install
+[user@el1 user]$ spack cd -b package && spack build-env package ./exe
+[user@el1 user]$ #edit code
+[user@el1 user]$ spack install
+[user@el1 user]$ spack cd -b package && spack build-env package ./exe
+[user@el1 user]$ #edit spack.yaml
+[user@el1 user]$ spack concretize -f
+[user@el1 user]$ spack install
+[user@el1 user]$ spack cd -b package && spack build-env package ./exe
+...
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/user_profiles/developers/useful_commands.html b/user_profiles/developers/useful_commands.html new file mode 100644 index 00000000..12ac2596 --- /dev/null +++ b/user_profiles/developers/useful_commands.html @@ -0,0 +1,260 @@ + + + + + + + + + Useful Commands for Development — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Useful Commands for Development

+

In the developer tutorial the granular Spack commands are shown to help youe become familiar with the process of building with Spack. +Using these commands (along with familiarization with the spack.yaml) will allow you to create a fully customized build environments.

+

In practice many of these commands are redundant and unneccesary for standard development workflows. +To assist with your workflow we’ve pre-scripted these commands in a set of quick-commands. +These commands are available in your shell once you’ve sourced $SPACK_MANAGER/scripts/quick_commands.sh, and provide a drop off point in the workflows based on your needs. +All of the quick-commands will echo all the calls to spack (pre-pended with a + ) so you can see what is being called and can reproduce them execution outside these scripts as needed.

+

Information on these commands are provided below.

+

For a quick reference: the commands that are anticipated to be the most commonly used are:

+ +
+

Environment setup process

+

As a reminder, the complete, granular list of steps to setup an environment after sourcing $SPACK_MANAGER/start.sh are:

+
    +

  1. spack manager create-env: create an environment

    2. +

  2. spack env activate: activate the environment you created

    3. +

  3. spack add: add root specs to the environment

    4. +

  4. spack manager develop: setup the source code you want to edit and configure the environment to use that code

    5. +

  5. spack manager external: optional step to link your environment against pre-built binaries

    6. +

  6. spack concretize: solve the dependency graph for your environment

    7. +

  7. spack install: build the software

    8. +
+
+
+

Environment loading process

+

The complete, granular list of steps to re-use an environment after sourcing $SPACK_MANAGER/start.sh are:

+
    +

  1. spack env activate: activate an environment

    2. +

  2. spack build env [package] [commands] or spack cd -b [spec] && bash -rcfile ../spack-build-env.txt: run a command in the build environment or dive into the build environment in a subshell

    3. +
+
+
+

Environment setup commands

+

The following commands are the convenience functions for setting up a development environment. +All of these commands will exit the shell with an active Spack environment whose name will be added +to your shell prompt. +Please note that these commands are principally constructing a valid spack.yaml file for you in your environment, +and that file can be manipulated as needed after the commands are executed.

+
+

quick-create

+

quick-create executes the environment setup process and exits at step 4. +If you supply specs with the --spec or -s flag then those will be added as root specs and you can effectively be at step 5 +spack manager develop.

+

When should I use quick-create?
+This command should be used by individuals who want to have control over the git clone process and/or locations of the source code +they are intending to develop. +spack manager develop gives you the abiilty to point to pre-cloned code, or to select the fork and branch you want to clone from. +If these are desirable features then you will need to run the remaining steps of the environment setup process +manually.

+
+
+

quick-create-dev

+

quick-create-dev executes the environment setup process and exits at step 5. +If you supply concrete specs, which means they have the name and version (i.e. amr-wind@main), then spack-manager develop will be called for you +and the default repos/branches will be cloned to the environment directory for you. +If you fail to supply a concrete spec then this command will give a warning letting you know the spec wasn’t concrete, and the behavior will stop at step 4. +In other words it will behave exactly like quick-create.

+

When should I use quick-create-dev?
+quick-create-dev should be used if you don’t mind accepting the default repo cloning, but need to specifiy the externals you will link against +with spack manager external or if you don’t want to use externals at all. +A common scenario for this is if you are building with the non-standard view that you can see from spack manager external --list. +The first view listed in the parenthesis for the latest timestamped snapshot is the default. +If this one doesn’t match your build needs then you will need to specifiy the correct one manually.

+
+
+

quick-develop

+

quick-develop executes the environment setup process and exits at step 7. +This command is intended to execute the entire setup process for the default development environment on a given machine. +Upon successful execution all that is required after this command is to run spack install since spack install will also perform +concretization. +The same requirement for valid concrete specs that was in quick-create-dev applies here along with all the same constraints.

+

When should I use quick-develop?
+quick-develop should be used if you want a rapid development environment without any need for customization. +This is the fastest and least number of commands to get you started and should work for standard development needs.

+
+
+
+

Environment re-use commands

+

These commands are designed to help you efficiently re-use an environment that has already been setup.

+
+

quick-activate

+

quick-activate executes the first two steps of the environment loading process +i.e. spack-start && spack env activate. +To use it you simply pass the directory path to the environment you wish to activate i.e. quick-activate $SPACK_MANAGER/environments/exawind +and it will activate the environment and add the name of the environment to your shell prompt.

+

When should I use quick-activate?
+Whenever you want to come back to an environment in a new shell. +There are really no down-sides to this command unless you don’t like the environment name being added to your prompt.

+
+
+

build-env-dive

+

build-env-dive takes a spec as an argument and will move you to the location of the build directory for that spec and launch a sub-shell using the spec’s build environment. +This command allows developers to work as if they had built the software manually outside of spack. +You can call make, make clean, make install, ctest etc. +Simply type exit to return to your original shell where you called build-env-dive. +It should be cautioned that diving into this environment can do things like change the version of git/python in your shell. +Also if you are doing a multi-compnent simply calling make will not update the entire stack like spack install will.

+

When should I use build-env-dive? +This command is most effective when you are just iterating on one software component and need to keep executing commands in that environment. +For a one off like checking a test spack build-env [spec] [command] is probably more efficient, but it is also clunkier to use. +In general build-env-dive command should be used freely as long as you are okay with it moving you to directories and are aware of the +potential issues related to opening a sub-shell with potentially different configurations. +In practice this has not been much of an issue.

+
+
+
+

Other Commands

+
+

remove-spack-prompt

+

This command takes no arguments unless you pass -h or --help. +It simply removes the prompt with the environment name that the quick-commands add.

+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/user_profiles/system_admins/creating_a_project.html b/user_profiles/system_admins/creating_a_project.html new file mode 100644 index 00000000..47bb635f --- /dev/null +++ b/user_profiles/system_admins/creating_a_project.html @@ -0,0 +1,393 @@ + + + + + + + + + Creating and configuring a Spack-Manager Project — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

Creating and configuring a Spack-Manager Project

+

Spack-Manager projects are the method for organizing configuration files and package repositories +associated with a given software application.

+

If a pre-configred project exists then it simply has to be add to the Spack-Manager configuration file. +This section will demonstrate the process of setting up a Spack-Manager project from scratch using the +ExaWind application.
+This is just an example that is not going to be kept up-to-date for Exawind since it is a living, independent project. +The actual ExaWind configuration can be found here.

+
+

Creating a Project from Scratch

+

A Project is really just a collection of directories and couple of optional python files. +In the spack-manager.yaml configuration file paths are provided to the projects that this instance of +Spack-Manager is supporting.

+
$ cat spack-manager/spack-manager.yaml
+
+spack-manager:
+    projects:
+    - $SCRATCH/exawind-demo
+
+$ ls -lh $SCRATCH/exawind-demo
+ls: /Users/psakiev/scratch/exawind-demo: No such file or directory
+
+
+

If a non-existent path is added to the Projects list in the spack-manager/spack-manager.yaml file +then these initial directories will automatically be created the first time a spack manager command is run. +It should also be noted that the autocompletion of variables inside these paths (such as the $SCRATCH environment +variable in this example, follow the same variable conventions utilized by Spack. +This is because Spack-Manager is importing and using the Spack code for these operations.

+
$ spack manager find-machine --list
+Project:         Machine:        Detected: (+/-)
+------------------------------------------------------------
+
+$ tree $SCRATCH/exawind-demo
+/Users/psakiev/scratch/exawind-demo
+├── configs
+└── repos
+
+3 directories, 0 files
+
+
+

Once the first spack manager command is run the project configs and repos directories get populated. +The configs directory is where machine specific spack configuration files are stored. +Since this directory is currently empty no machines show up when spack manager find-machine --list is run. +The next step is to add some machines and configuration files. +Note that machines is a loose term, and it is really a bifurcation of configurations. +The term machine was selected since application projects typically have to tweak their spack configurations +on each new machine/platform.

+
+
+

Populating Machine Specific Configurations

+

Directories within the project’s configs directory will be delineated by their names. +Let’s add a directory named darwin inside the configs directory and re-run spack manager find-machine --list.

+
$ mkdir $SCRATCH/exawind-demo/configs/darwin
+$ spack manager find-machine --list
+Project:         Machine:        Detected: (+/-)
+------------------------------------------------------------
+exawind-demo     darwin          -
+
+
+

darwin is automatically picked up as an available machine by the find-machine command, and any configuration files that +are added inside this directory will be added to an environment created with a darwin machine specified. +It should also be noted that the project name exawind-demo comes from the name of the parent directory. +Now configurations can be added. +The following two configurations are used by ExaWind.

+
# config.yaml
+config:
+  mirrors:
+    e4s: https://cache.e4s.io
+
+
+
# packages.yaml
+packages:
+  hypre:
+    variants: +shared~fortran
+  all:
+    compiler: [apple-clang, gcc, clang]
+    providers:
+      mpi: [mpich, openmpi]
+
+
+
+

Anonymous Machines

+

There are two anonymous machines that are reserved for project and users to utilize: base and user. +The configs/base directory is designed to hold project wide configurations that are the defaults utilized by every environment. +For example, the software project has non-default package variants they wish to use uniformly across all platforms these could +be set in the configs/base/packages.yaml file.

+

The configs/users directory is one that allows users to set their own personal preferences or make tweaks before pushing them +to the whole team. An example here is if one user really prefers a specific flavor of MPI and the software project is not constrained +then they could configure that in the configs/user/packages.yaml file.

+

The hierarchy of precedent for these configs are:

+
    +

  1. user

    2. +

  2. machine

    3. +

  3. base +where the smaller number means higher precedent.

    4. +
+

So any configurations in base are not the law and can be overridden on each machine as necessary. +An example of this would be if the project prefers to build with +shared but on specific platform can only support ~shared. +As a reminder, this hierarchy is only for creating the default environment configuration on each platform when it is created. +These are added to the spack.yaml via entries in the includes list. +Each environment can still be customized by modifying the spack.yaml file and using additional configuration techniques.

+

For completeness, the optional base and user directories will now be added to the exawind-demo project.

+
$ mkdir $SCRATCH/exawind-demo/configs/base
+$ mkdir $SCRATCH/exawind-demo/configs/user
+$ spack manager find-machine --list
+Project:         Machine:        Detected: (+/-)
+------------------------------------------------------------
+exawind-demo     darwin          -
+
+
+

The output above shows how these config directories are ignored by the find-maachine command. +Next we’ll add some of the base configs used by ExaWind to the base directory.

+
# config.yaml
+config:
+  source_cache: ~/.spack_downloads
+  misc_cache: $spack/../.cache
+  build_stage:
+    - $spack/../stage
+  concretizer: clingo
+
+
+
# concretizer.yaml
+concretizer:
+  unify: false
+  reuse: false
+
+
+

Now if we create an environment using spack manager create-env --machine darwin we will see all the configs that have been added in the include.yaml file.

+
$ spack manager create-env --machine darwin -d $SCRATCH/example-env
+making /Users/psakiev/scratch/example-env
+
+$ cat $SCRATCH/example-env/spack.yaml
+# This is a Spack Environment file.
+#
+# It describes a set of packages to be installed, along with
+# configuration settings.
+spack:
+  # add package specs to the `specs` list
+  specs: []
+  view: false
+  concretizer:
+    unify: true
+  include:
+  - include.yaml
+
+$ cat $SCRATCH/example-env/include.yaml
+concretizer:
+  unify: false
+  reuse: false
+packages:
+  hypre:
+    variants: +shared~fortran
+  all:
+    compiler: [apple-clang, gcc, clang]
+    providers:
+      mpi: [mpich, openmpi]
+config:
+  mirrors:
+    e4s: https://cache.e4s.io
+  source_cache: ~/.spack_downloads
+  misc_cache: $spack/../.cache
+  build_stage:
+  - $spack/../stage
+  concretizer: clingo
+
+
+
+
+
+

Configuring Machine Auto-detection

+

The last column from the output of spack manager find-machine --list indicates if the configuration +was detected for the current machine. +The default behavior is to detect nothing and require users to specify the machine they want to use. +However, setting up automatic detection is simple and highly configurable for each project and each machine.

+

To add detection a project must have a python file named find-[project].py in the top-level directory of the project (exawind-demo in this example). +find-[project].py needs to have a method named detector that takes a string with the machine name and returns +True or False depending on if the current machine meets the criteria for that name.

+

Here is an example find-exawind-demo.py script

+
import sys
+
+def detector(name):
+    """
+    A function that will check if the supplied name/machine
+    matches a known machine configuration
+    """
+    # dictionary that is easily extensible where key is the name we want to match
+    # and the value is function that can be evaluated to test the actual system we
+    # are one
+    known_machines = {
+        "darwin": lambda: sys.platform == "darwin",
+    }
+
+    if name in known_machines:
+        return known_machines[name]()
+    else:
+        return False
+        
+
+
+

Now when the find-machine command is run the darwin machine will be detected.

+
$ spack manager find-machine --list
+Project:         Machine:        Detected: (+/-)
+------------------------------------------------------------
+exawind-demo     darwin          +
+
+
+

Users are free to implement and sort of detection script they want.
+The only requirements are that the method detector have a positional +argument for the name of the machine to check for, and returns a boolean to indicate if that supplied name +was detected.

+
+
+

Setting up Spack Package Repositories

+

The [Project]/repos directory is a place holder for package repositories that are paired with the softwware applications development/deployment. +The simplest way to ensure the appropriate repos are included is to add a reference to them in +[Project]/configs/base/repos.yaml file. +This is a way to ensure that any environment created with Spack-Manager for the desired project will include the repos.

+

An example for ExaWind is as follows:

+
# repos.yaml
+repos:
+  - $spack/../repos/exawind
+
+
+

Where the $spack is a supported +configuration variable +that will be expanded by spack. +This works for ExaWind because ExaWind creates a fixed mirror of spack that is submoduled +into their Project repository.

+

Utilizing a configuration variable, environment variable, or manually updating the repo paths are currently +the only way to point to repos in arbitrary locations on the filesystem. +Users may also add the copy_repos: true flag to their projects inside the spack-manager.yaml configuration +file if they wish to just automatically copy the repo files locally to an environment when it is created.

+
spack-manager:
+  projects:
+  - $SCRATCH/exawind-demo
+    copy_repos: true
+
+
+

In this case the repo specification would be properly resolved with the following repo.yaml file in the base configs.

+
# repos.yaml
+repos:
+  - $env/repos/exawind
+
+
+

Now when an environment is created the [Projects]/repos directory will be copied completely to the environment, and +the environment will look for the copy relative to its own location.

+

Please note, that these are mainly small tricks to utilize spack’s builtin path resolution strategies. +Additional work in the future is anticipated to make this a more seamless setup and transition.

+
+
+

Adding Version Control

+

At this point the exawind-demo project is populated with an initial set of configurations. +It is highly suggested that it be placed under some form of version control. +git is by far the most popular tool for version control at the moment. +A suggested .gitignore file would look something like the following:

+
# basic python files
+__pycache__
+*pyc
+# some operations in spack-manager can currently create this directory
+.tmp
+
+
+
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/user_profiles/system_admins/system_admins.html b/user_profiles/system_admins/system_admins.html new file mode 100644 index 00000000..b750de4d --- /dev/null +++ b/user_profiles/system_admins/system_admins.html @@ -0,0 +1,134 @@ + + + + + + + + + System Administrator Documentation — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

System Administrator Documentation

+

This section of documentation is for users who will be using Spack-Manager to manage +the software development process for software developers and/or end users on specific machines.

+
+ +
+
+ + +
+
+ +
+
+
+
+ + + + \ No newline at end of file diff --git a/user_profiles/user_profiles.html b/user_profiles/user_profiles.html new file mode 100644 index 00000000..c3449986 --- /dev/null +++ b/user_profiles/user_profiles.html @@ -0,0 +1,133 @@ + + + + + + + + + User Profiles — Spack-Manager 0.1 documentation + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+ +
+ +
+
+
+
+ + + + \ No newline at end of file