Tykky

Johdanto

Tykky on työkalukokonaisuus, joka helpottaa ja tehostaa ohjelmistojen asennusta HPC-järjestelmissä 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ökalun 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. Joitakin edistyneitä käyttötapauksia ei käsitellä tässä – niitä varten katso README GitHub-repositoriosta.

Tykky-moduuli

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

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 wrapper-skriptit, jotta se toimii samalla tavalla kuin muut tykky-pohjaiset ympäristöt.

Kaikissa tapauksissa säiliöity ympäristö tuotetaan annettuun kohdehakemistoon. Hakemisto sisältää bin/-alihakemiston, jossa ovat suoritettavat tiedostot. Jos esimerkiksi 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 ikään kuin sitä ajettaisiin 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 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 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 ennen versiota 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 sitä 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ääkseen, 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

Jos haluat 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 omaa Tykky-asennusta käytetään Puhdin selainkäyttöliittymän Jupyterissa, Jupyter-sovellussivulta.

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ä --mamba-valitsin.

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

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-paketinhallinta.

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ä tavalliseen tapaan pip:llä, mutta silloin 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 komennoille, jotka 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ä.

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

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äntäjärjestelmästä, 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 "tavallisten" 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-osoite (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 / kohdepolun suoritettaville tiedostoille. 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 kirjautumissolmun käytettävissä olevat resurssit eivät välttämättä 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

Jos haluat poistaa Tykky-asennuksen, poista kansio .

Tykky-asennuksia voidaan myös siirtää:

Saman supertietokoneen sisällä kansiosta toiseen siirrä kansio komennolla mv uuteen sijaintiin.
Puhdin ja Mahdin välillä käytä rsync:iä. Jos kopioit Mahtiin, kirjaudu Mahtiin 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.