Tykky

Johdanto

Tykky on työkalukokonaisuus, joka tekee ohjelmistojen asentamisesta HPC-järjestelmiin helpompaa ja 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 kääreitä, 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ä suorituksen 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 edistyneitä käyttötapauksia ei käsitellä tässä – niitä varten katso GitHub-repositorion README.

Tykky-moduuli

Tykky-työkalujen käyttämiseksi:

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ää siihen kääreskriptit, 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 suoritettavat tiedostot. Esimerkiksi jos luot ympäristön Python-kirjastoille, bin/python3 käyttäytyy kuten Python, johon annetut riippuvuudet on asennettu. Se suoritetaan säiliössä, mutta tykyn ansiosta se toimii läpinäkyvästi aivan kuin se toimisi suoraan tavallisessa järjestelmässä.

Jos lisäät bin/-hakemiston $PATH-ympäristömuuttujaasi, "säiliöidyt" komennot suoritetaan oletuksena tavallisen järjestelmän tarjoaman python3:n sijaan. Voit myös antaa moduulitiedoston tehdä tämän puolestasi, 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 suoritettavat tiedostot 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 tähän ympäristöön haetaan, 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äisestä 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 muita Condan asentamia suoritettavia tiedostoja samalla tavalla kuin jos olisit aktivoinut ympäristön.

Jupyterin käyttäminen Tykky-asennuksen kanssa

Jotta voit käyttää Tykky-asennusta Jupyterin kanssa, sisällytä 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 käytät omaa Tykky-asennustasi Puhdin selainkäyttöliittymän Jupyterin kanssa, Jupyter-sovelluksen sivulta.

Mamba

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

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

Lisää lisäpaketteja pipillä tai uv:lla

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

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

Oletuksena riippuvuuksien asentamiseen käytetään pippiä. Lisäksi --uv-valitsimen käyttö yhdessä --mamba-valitsimen kanssa mahdollistaa nopeamman asennuksen. Vastaavan env.yml-tiedoston on myös sisällettävä uv-paketinhallintaohjelma.

conda-containerize new -r req.txt --mamba --uv --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.

Jos asennusta halutaan oikeasti muokata, voidaan käyttää avainsanaa update yhdessä vaihtoehdon --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. Samat huomautukset ja vaihtoehdot Conda-asennuksen muokkaamiseen pätevät myös tässä.

Vaihtoehtoisesti Python-asennusten hallintaan voidaan käyttää uv:ta antamalla --uv-valitsin. Vaatimustiedostossa luetellut paketit asennetaan tällöin komennolla uv pip install, mikä mahdollistaa riippuvuuksien nopeamman asennuksen.

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

Tärkeää: Tämä Python ei voi itse olla säiliöpohjainen, koska sisäkkäisyys ei ole mahdollista!

Lisäksi on olemassa --slim-valitsin, joka käyttää pohjana valmiiksi rakennettua minimaalista Python-säiliötä, jossa on paljon uudempi Python-versio. Ilman --slim-valitsinta 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 kääreet olemassa olevissa Apptainer/Singularity-säiliöissä oleville 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 "tavallisten" asennusten välillä).
Asentaa Docker-kuvissa saatavilla olevia työkaluja, mukaan lukien kääreiden luominen.

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

<container> voi olla paikallinen tiedostopolku tai mikä tahansa Apptainer/Singularityn hyväksymä URL-osoite (esim. docker:// oras://)
-w-vaihtoehdon on oltava absoluuttinen polku (tai pilkuilla erotettu lista) säiliön sisällä. Tällöin kääreet luodaan automaattisesti kohdehakemistojen suoritettaville tiedostoille / kohdepolulle. Jos et tiedä säiliössä olevien suoritettavien tiedostojen 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 kirjautumissolmulla 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 15 GB local disk on Mahti and 20 GB default amount on Roihu (increase if needed)
# In Mahti:
sinteractive --account <project> --time 1:00:00 --cores 8 --tmp 15
# In Roihu:
sinteractive --account <project> --time 1:00:00 --cores 8 

# 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.
Roihun ja Mahdin välillä käytä rsync:iä. Jos kopioit Roihuun, kirjaudu Mahdille ja siirry kansioon, johon haluat siirtää Tykky-asennuksen, ja käytä sitten:

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

Monimutkaisempi esimerkki

Esimerkki työkalun repositoriossa.