Tykky

Johdanto

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

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 ajetaan 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 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 ohjelmat otetaan automaattisesti käyttöön. Voit palata aiempaan ympäristöösi komennolla tykky deactivate.

Conda-pohjainen asennus

Lisensoinnista

Jos käytät Tykyn versiota 0.4.0 vanhemmilla versioilla asennettuja ympäristöjä, varmista ennen komennon käyttöä, että olet lukenut ja ymmärtänyt Minicondan ja käytettyjen kanavien lisenssiehdot.

Tykyn 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äisestä luetellusta kanavasta. Jos pakettiversioita ei ole määritetty, Conda asentaa aina uusimmat versiot.

2) Luo asennusta varten uusi hakemisto <install_dir>. /projappl/<your_project>/... on suositeltu.

3) Luo asennus:

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

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

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

5) Nyt voit kutsua python-komentoa 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 Roihussa on selainkäyttöliittymän kautta. Katso lisätietoja siitä, miten omaa Tykky-asennusta käytetään Roihun selainkäyttöliittymän Jupyterissa, 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, 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:iin 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 silloin Python-paketit sijaitsevat rinnakkaisessa tiedostojärjestelmässä, mitä ei suositella suuremmille asennuksille.

Jos asennusta halutaan 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ä.

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 käyttää sitä Python-versiota, joka 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 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 (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 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 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 (provides 20 GiB of local disk under $TMPDIR)
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 toisen supertietokoneen (esim. LUMI) välillä käytä rsync:iä. Jos haluat esimerkiksi kopioida asennuksen Roihusta LUMIin, kirjaudu LUMIin ja siirry kansioon, johon haluat siirtää Tykky-asennuksen, ja käytä sitten:

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

Yhteyden muodostaminen Roihuun vaatii voimassa olevan SSH-varmenteen, joten varmista, että välität SSH-agenttisi edelleen, mukaan lukien varmenteesi, kun kirjaudut toiseen supertietokoneeseen. Katso SSH-agentin edelleenvälitysohjeet Linuxille/macOS:lle ja Windowsille.

Monimutkaisempi esimerkki

Esimerkki työkalun repositoriossa.