Tykky

Johdanto

Tykky on työkalukokonaisuus, joka helpottaa ohjelmistojen asennusta HPC-järjestelmiin ja tekee siitä tehokkaampaa Apptainer-säiliöiden avulla.

Tykyn käyttötapauksia:

Conda-asennukset, jotka perustuvat Condan environment.yml-tiedostoon.
Pip-asennukset, jotka perustuvat pipin requirements.txt-tiedostoon.
Säiliöasennukset, jotka perustuvat olemassa oleviin Docker- tai Apptainer/Singularity-kuviin.
- Tämä sisältää asennukset Bioconda-kanavasta, katso esimerkki tästä ohjeesta.

Tykky kapseloi asennukset Apptainer/Singularity-säiliön sisään parantaakseen käynnistysaikoja, vähentääkseen I/O-kuormaa ja pienentääkseen tiedostojen määrää suurissa rinnakkaisissa tiedostojärjestelmissä. Lisäksi Tykky luo wrapperit, jotta asennettuja ohjelmistoja voidaan käyttää (lähes) kuin niitä ei olisi säiliöity. Työkalujen valinnasta ja asetuksista riippuen joko koko isäntäjärjestelmän tiedostojärjestelmä tai rajattu osa siitä on näkyvissä ajon ja asennuksen aikana. Tämä tarkoittaa, että on mahdollista kapseloida esimerkiksi mpi4py:tä käyttävät asennukset, jotka tukeutuvat isäntäjärjestelmän tarjoamaan MPI-asennukseen.

Tämä dokumentaatio kattaa osan toiminnallisuuksista ja keskittyy Condaan ja Pythoniin. Muutamia edistyneempiä käyttötapauksia ei käsitellä tässä – niitä varten katso GitHub-repositorion README.

Tykky-moduuli

Tykky-työkalujen käyttöönottamiseksi:

1) Yleensä on parasta ensin poistaa kaikki muut moduulit käytöstä:

module purge

2) Lataa Tykky-moduuli:

module load tykky

Yleiskuva

Tykky tarjoaa komennot conda-containerize ja pip-containerize, jotka tuottavat säiliöidyn ympäristön Conda-ympäristötiedoston tai pip-vaatimustiedoston perusteella. Komento wrap-install kapseloi olemassa olevan Conda-asennuksen säiliöön. Komento wrap-container ottaa olemassa olevan säiliön ja lisää wrapper-skriptit, jotta se toimii samalla tavalla kuin muut tykkyyn perustuvat ympäristöt.

Kaikissa tapauksissa säiliöity ympäristö tuotetaan annettuun kohdehakemistoon. Hakemisto sisältää bin/-alihakemiston, jossa ovat ajettavat ohjelmat. Jos esimerkiksi luot ympäristön Python-kirjastoille, bin/python3 käyttäytyy kuten Python, johon annetut riippuvuudet on asennettu. Se toimii säiliössä, mutta tykyn ansiosta se toimii läpinäkyvästi aivan kuin se toimisi suoraan normaalissa järjestelmässä.

Jos lisäät bin/-hakemiston $PATH-ympäristömuuttujaasi, "säiliöidyt" komennot suoritetaan oletuksena normaalin järjestelmän tarjoaman python3:n sijaan. Voit myös käyttää tähän moduulitiedostoa, ja itse asiassa näin monet CSC-ympäristön moduuleista on tuotettu.

Sen sijaan, että muokkaisit $PATH:ia käsin, voit myös aktivoida tykky-asennuksen komennolla tykky activate <install_dir>, missä <install_dir> on kohdehakemisto, jota tykky käytti asennuksen aikana. Kehotteesi näyttää tällöin (install_dir), ja asennetut ohjelmat otetaan automaattisesti käyttöön. Voit palata aiempaan ympäristöösi komennolla tykky deactivate.

Conda-pohjainen asennus

Lisensoinnista

Jos käytät Tykky-versioilla, jotka ovat vanhempia kuin 0.4.0, asennettuja ympäristöjä, varmista ennen komennon käyttöä, että olet lukenut ja ymmärtänyt Minicondan ja käytettyjen kanavien lisenssiehdot.

Tykky-versiot 0.4.0 ja uudemmat käyttävät Miniforgea, johon yllä olevat lisenssirajoitukset eivät päde. Katso Tykyn julkaisuhistoria.

1) Luo Conda-ympäristötiedosto env.yml:

Luo uusi tiedosto käsin tai
Luo tiedosto olemassa olevasta Conda-asennuksesta. Esimerkiksi: conda env export -n <target_env_name> > env.yml.
- Jos olemassa oleva ympäristö on Windows- tai MacOS-koneella, --from-history-valitsin voi olla tarpeen, jotta saadaan Linuxille sopiva .yml-tiedosto.
- Jos olemassa oleva ympäristö on Linux-koneella, jossa on x86-suoritinarkkitehtuuri, on myös mahdollista käyttää --explicit-valitsinta.

Esimerkki sopivasta env.yml-tiedostosta:

channels:
  - conda-forge
dependencies:
  - python=3.8.8
  - scipy
  - nglview

Info

Kenttä channels luettelee, mistä kanavista paketit tulee hakea tähän ympäristöön, kun taas kenttä dependencies luettelee varsinaiset Conda-paketit, jotka asennetaan ympäristöön. Huomaa, että Conda käyttää kanavaprioriteettia määrittäessään, mistä paketit asennetaan, eli se yrittää ensin asentaa paketit ensimmäisenä luetellusta kanavasta. Jos pakettiversioita ei ole määritelty, Conda asentaa aina uusimmat versiot.

2) Luo asennusta varten uusi hakemisto <install_dir>. Hakemistoa /projappl/<your_project>/... suositellaan.

3) Luo asennus:

conda-containerize new --prefix <install_dir> env.yml

4) Lisää hakemisto <install_dir>/bin $PATH:iisi:

export PATH="<install_dir>/bin:$PATH"

5) Nyt voit kutsua python:ia ja kaikkia muita Condan asentamia ohjelmia samalla tavalla kuin jos olisit aktivoinut ympäristön.

Jupyterin käyttäminen Tykky-asennuksen kanssa

Jotta voit käyttää Tykky-asennusta Jupyterin kanssa, lisää oikea conda-paketti Conda-ympäristötiedostoosi: jupyterlab JupyterLabia varten tai notebook Jupyter Notebookeja varten conda-forge-kanavasta. Myös muita JupyterLab-laajennuksia voidaan asentaa, esimerkiksi jupyterlab-git tai dask-labextension.

Paras tapa käyttää Jupyteria Puhdissa tai Mahdissa on selainkäyttöliittymän kautta. Katso lisätietoja siitä, miten omaa Tykky-asennusta käytetään Puhdin selainkäyttöliittymän Jupyterissa, Jupyter-sovelluksen sivulta.

Pip Condan kanssa

Jos haluat asentaa joitakin lisäpaketteja pipillä, lisää argumentti -r <req_file>, esimerkiksi:

conda-containerize new -r req.txt --prefix <install_dir> env.yml

Mamba

Työkalu tukee myös Mamban käyttöä pakettien asentamiseen. Mamba löytää sopivat paketit usein paljon nopeammin kuin Conda, joten se on hyvä vaihtoehto, kun tarvittavien pakettien lista on pitkä. Ota tämä ominaisuus käyttöön lisäämällä valitsin --mamba.

conda-containerize new --mamba --prefix <install_dir> env.yml

Esimerkki alusta loppuun

Luo uusi Conda-pohjainen asennus käyttäen aiempaa env.yml-tiedostoa.

mkdir MyEnv
conda-containerize new --prefix MyEnv env.yml

Kun asennus on valmis, lisää asennushakemisto PATH:iisi ja käytä sitä normaalisti.

$ export PATH="$PWD/MyEnv/bin:$PATH"
$ python --version
3.8.8
$ python3
Python 3.8.8 | packaged by conda-forge | (default, Feb 20 2021, 16:22:27) 
[GCC 9.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import scipy
>>> import nglview
>>>

Conda-asennuksen muokkaaminen

Tykky-asennukset sijaitsevat säiliössä, joten niitä ei voi muokata suoraan. Pieniä Python-paketteja voidaan lisätä normaalisti pip:llä, mutta tällöin Python-paketit sijaitsevat rinnakkaisessa tiedostojärjestelmässä, mitä ei suositella suuremmille asennuksille.

Jotta asennusta voidaan oikeasti muokata, voidaan käyttää avainsanaa update yhdessä valitsimen --post-install <file> kanssa, joka määrittää bash-skriptin, jonka komennot suoritetaan asennuksen päivittämiseksi. Komennot suoritetaan Conda-ympäristö aktivoituna.

conda-containerize update <existing installation> --post-install <file>

Missä <file> voisi sisältää esimerkiksi:

conda install -y numpy
conda remove -y nglview
pip install requests

Tässä tilassa koko isäntäjärjestelmä on käytettävissä, mukaan lukien kaikki ohjelmistot ja moduulit.

Pip-pohjaiset asennukset

Joskus et tarvitse täysimittaista Conda-ympäristöä tai saatat mieluummin käyttää pippiä Python-asennusten hallintaan. Tässä tapauksessa voidaan käyttää:

pip-containerize new --prefix <install_dir> req.txt

missä req.txt on tavallinen pipin vaatimustiedosto. Conda-asennuksen muokkaamista koskevat huomautukset ja valinnat pätevät myös tässä.

Huomaa, että pip-containerize:n käyttämä Python-versio on ensimmäinen polusta löytyvä Python-ohjelma, joten ladatut moduulit vaikuttavat siihen.

Tärkeää: Tämä Python ei voi itse olla säiliöpohjainen, koska sisäkkäisiä säiliöitä ei voi käyttää!

Lisäksi on olemassa valitsin --slim, joka käyttää pohjana valmiiksi rakennettua minimaalista Python-säiliötä, jossa on paljon uudempi Python-versio. Ilman valitsinta --slim koko isäntäjärjestelmä on käytettävissä, kun taas valitsimen kanssa järjestelmäasennuksia (eli /usr, /lib64, ...) ei enää oteta isännältä, vaan ne tulevat säiliön sisältä.

Säiliöpohjaiset asennukset

Tykky tarjoaa myös mahdollisuuden:

Luoda wrapperit olemassa olevien Apptainer/Singularity-säiliöiden työkaluille niin, että niitä voidaan käyttää läpinäkyvästi (ei tarvitse lisätä eteen apptainer exec ... tai muokata skriptejä, jos vaihdetaan säiliöityjen versioiden ja "normaalien" asennusten välillä).
Asentaa Docker-kuvissa saatavilla olevia työkaluja, mukaan lukien wrapperien luominen.

wrap-container -w /path/inside/container <container> --prefix <install_dir>

<container> voi olla paikallinen tiedostopolku tai mikä tahansa Apptainer/Singularityn hyväksymä URL (esim. docker:// oras://)
-w-valitsimen on oltava absoluuttinen polku (tai pilkuilla erotettu lista) säiliön sisällä. Wrapperit luodaan tällöin automaattisesti kohdehakemistojen ohjelmille / kohdepolulle. Jos et tiedä säiliössä olevien ohjelmien polkua, avaa komentotulkki säiliön sisällä ja käytä which-komentoa. Komentotulkin avaaminen:
- Jos kyseessä on olemassa oleva paikallinen Apptainer/Singularity-tiedosto: singularity shell image.sif.
- Jos kyseessä on Docker- tai ei-paikallinen Apptainer/Singularity-tiedosto, luo ensin asennus jollakin polulla ja käynnistä sitten luotu _debug_shell.

Muistivirheet

Hyvin suurissa asennuksissa kirjautumissolmun käytettävissä olevat resurssit eivät ehkä riitä, jolloin Tykky epäonnistuu MemoryError-virheeseen. Tässä tapauksessa asennus on tehtävä laskentasolmulla, esimerkiksi käyttämällä interaktiivista istuntoa:

# Start interactive session, here with 12 GB memory and 15 GB local disk (increase if needed)
# In Puhti:
sinteractive --account <project> --time 1:00:00 --mem 12000 --tmp 15
# In Mahti:
sinteractive --account <project> --time 1:00:00 --cores 8 --tmp 15

# Load Tykky
module purge
module load tykky

# Run the Tykky commands as described above, e.g.
conda-containerize new --prefix <install_dir> env.yml

Tykky-asennuksen siirtäminen ja poistaminen

Tykky-asennuksen poistamiseksi poista kansio .

Tykky-asennuksia voidaan myös siirtää:

Saman supertietokoneen sisällä kansiosta toiseen siirrä kansio uuteen sijaintiin komennolla mv.
Puhdin ja Mahdin välillä käytä rsync:iä. Kopioidaksesi Mahdille kirjaudu Mahdille ja siirry kansioon, johon haluat siirtää Tykky-asennuksen, ja käytä sitten:

rsync -al <username>@puhti.csc.fi:<install_dir> .

Monimutkaisempi esimerkki

Esimerkki työkalun repositoriossa.