# $Revision: 12143 $
# $Author: saulius $
# $Date: 2025-02-10 19:59:03 +0000 (Mon, 10 Feb 2025) $

Sugeneruoti atominį objekto modelį
==================================
         Saulius Gražulis
         Vilnius, 2025 m.

SUSITARIMAI
===========

Raktiniai žodžiai "TURI" (angl. "MUST"), "NEGALI" (angl. "MUST NOT"),
"NETURI" (angl. "SHALL NOT"), "PRIVALO" (angl. "REQUIRED", "SHALL"),
"TURĖTŲ" (angl. "SHOULD"), "NETURĖTŲ" (angl. "SHOULD NOT"),
"REKOMENDUOJAMA" (angl. "RECOMMENDED"), "GALI" (angl. "MAY"), ir
"NEPRIVALOMA(S)" (angl. "OPTIONAL") šiame tekste interpretuojami pagal
atitinkamus apibrėžimus dokumente RFC 2119 [1].

PROGRAMA
========

Parašykite Perl arba Ada programavimo kalba programą, kuri patalpina
nurodytus atomus ant duoto paviršiaus, duotos kreivės 3D erdvėje ar
duotame tūryje (kitaip tariant, duotoje daugdaroje). Programa turi
veikti visose šiuo metu palaikomose Debian, Ubuntu ir suderinamose
sistemose.

Programa turi skaityti parametrų failus, nurodytus komandinėje
eilutėje. Failų formatas turi būti CSV [2] arba TSV [3]. Kiekviename
faile gali būti neprivaloma pirmoji antraštės eilutė su stulpelių
pavadinimais. Toliau kiekvienoje eilutėje turi būti po pilną parametrų
rinkinį atomų aibės generavimui. Gali būti nurodyta keletas įvesties
(parametrų) failų, ir kiekviename gali būti po keletą parametrų
rinkinių. Jei nei vienas failas komandinėje eilutėje nenurodytas,
programa TURI skaityti iš standartinės įvesties (STDIN) tuo pačiu
formatu, kaip ir iš failų.

Kiekvienam parametrų rinkiniui programa TURI sugeneruoti atomų aibę ir
užrašyti ją į standartinę išvestį XYZ [4] formatu. Atomų tipai gali
būti nurodomi arba kaip atominiai numeriai, arba kaip atomų vardai
Periodinėje elementų sistemoje.

Jei parametrų faile pateikti stulpelių vardai parametrai TURI būti
identifikuojami pagal stulpelių vardus. Jei stulpelių vardai
nenurodyti, parametrai turi būti identifikuojami pagal jų numatytąją
tvarką. Tiek priimtini parametrų vardai, tiek jų numatytoji tvarka
turi būti dokumentuoti programos komentaruose ir programos pagalbos
išvestyje. Programos įvestyje gali būti vienu metu pateikiami įvairūs
failai, tiek su antraštėmis, tiek be jų.

Parametrų failuose gali būti nepilni parametrų rinkiniai. Parametrų
failuose su stulpelių vardais bet kurie parametrai gali būti
praleisti. Parametrų failuose be stulpelių vardų turi būti laikoma,
kad pateikti yra pirmieji (pagal numatytąją tvarką) parametrai, o
praleisti visi tolimesnieji. Pvz., jei programa naudoja 10 parametrų, o
faile pateikti tik 5 stulpeliai, laikoma, kad pateikti parametrai nuo
1 iki 5 (pradedant numeraciją nuo 1), o parametrų nuo 6 iki 10
nėra. Trūkstamiems parametrams programa turi priimti protingą
numatytąją reikšmę (angl. default value). Jei numatytosios reikšmės
programa pasiūlyti negali, ji turi išvesti suprantamą klaidos
pranešimą apie situaciją.

Programos vardas
----------------

Programos vardas turi būti sudaromas pagal schemą:

gen-<daugdaros-vardas>-atoms

arba

gen_<daugdaros-vardas>_atoms

kur simbolių rinkinys <daugdaros-vardas> TURI būti pakeičiamas Jums
paskirtos daugdaros (figūros) vardu. Pavyzdžiui, jei generuojate
atomus sferos paviršiuje, programos vardas turi būti

gen-sphere-atoms

arba

gen_sphere_atoms

Programos varde *negali* būti plėtinio!

Programos iškvietimas
---------------------

Turi būti galimybė iškviesti programą visais žemiau nurodytais būdais:

gen-sphere-atoms parameter_set_1.tsv parameter_set_2.csv
gen-sphere-atoms < parameters.tsv
gen-sphere-atoms *.tsv /dev/stdin *.csv

REIKALAVIMAI ĮGYVENDINIMUI
==========================

Šioje užduotyje failų įvestis, skaičiavimai ir išvestis privalo būti
realizuoti pačioje programoje, naudojant standartines programavimo
kalbos teikiamas funkcijas, nenaudojant išorinių bibliotekų. Išorines
bibliotekas, kiek minimaliai reikia, galima naudoti matematinėms
funkcijoms, atsitiktinių skaičių generatoriui ir eilučių įvesčiai ir
išvesčiai.

ĮVESTIS
=======

Programos įvestis turi būti CSV [2] arba TSV [3] formato failai, su
stulpelių vardais, dokumentuotais, kaip nurodyta aukščiau. Siekiant
išvengti išorinių priklausomybių, ir supaprastinti kodą, leidžiama
apriboti CSV failų formatą, reikalaujant, kad kiekvienas CSV įrašas
būtų vienoje eilutėje, o reikšmėse nebūtų kablelių.

Paskutinis parametras TURĖTŲ būti atsitiktinių skaičių generatoriaus
inicializuojanti reikšmė, kuri leistų tiksliai pakartoti atliktą
skaičiavimą.

Pirmasis parametras TURI būti parametras "Nr", kuris nurodo parametrų
rinkinio numerį faile. Šis parametras, jei pateiktas, TURĖTŲ būti
unikalus faile.

Pavyzdys
--------

Programai, kuri generuoja atomus sferos paviršiuje, gali būti
naudojamas toks parametrų failo turinys:

Nr,AtomType,AtomCount,CenterX,CenterY,CenterZ,Radius,RndSeed
1,C,100,10.5,9.8,12.6,15.0,34345345
2,0,120,0,0,0,80.0,34546456

Čia atomo tipas "0" gali būti naudojamas tam, kad pažymėti, jog šiuo
parametrų rinkiniu aprašytoje atomų aibėje programa turi generuoti
atsitiktinius atomų tipus.

IŠVESTIS
========

Du vandenilio atomai, sugeneruoti ant 10 Å spindulio sferos, gali
atrodyti taip:

2
gen_sphere_atoms <<< 1,H,2,0,0,0,10.0,38973458
H 0.0 0.0  10.0
H 0.0 0.0 -10.0

arba, jei naudojami atominiai numeriai vietoj atomų vardų:

2
gen-sphere-atoms <<< 1,1,2,0,0,0,10.0,38973458
1 0.0 0.0  10.0
1 0.0 0.0 -10.0


KLAIDŲ DIAGNOSTIKA
==================

Programa GALI naudoti naudojamos Ada arba Perl programavimo sistemos
diagnostikos galimybes. Galima naudoti Perl kalbos 'warn()' ir 'die()'
paprogrames ten, kur jos tinka.

Klaidų pranešimai TURĖTŲ pateikti mažų mažiausiai šią informaciją:

-- programos, kuri nustatė klaidą, pavadinimą;

-- failo, kuris buvo apdorojamas klaidos metu, vardą. Naudokite vardą
   "-" (kabutėse), arba vardą „STDIN“ (be kabučių), jei klaidos metu
   buvo apdorojamas STDIN (jei tinka);

-- apdorojamo failo eilutės numerį ir apdorojamo simbolio poziciją
   eilutėje klaidos vietoje (jei tinka);

-- trumpą (20–40 simbolių) įvesties teksto citatą, parodančią aptiktos
   klaidos vietą (jei tinka);

-- trumpą bet informatyvų pranešimą apie tai, kokia yra klaidos
   priežastis ir kaip galima klaidą pataisyti. Šauktukų klaidų
   pranešimuose naudoti NEREIKIA.

Programa turi diagnozuoti mažiausiai šias klaidas:

-- neįmanoma atidaryti parametrų failo;

-- įvyko klaida skaitant parametrų failą;

-- neteisingas perskaityto parametro tipas arba formatas;

-- nežinomas parametro vardas stulpelio antraštėje;

-- įvyko klaida rašant išvesties duomenis;

-- įvyko matematinė skaičiavimo klaida (pvz. dalyba iš nulio).

Klaidos pranešimo pavyzdys
--------------------------

gen_sphere_atoms: cannot open parameter file "param.tsv" -- permission denied.

PABAIGOS KODAS (angl. Exit Status)
==================================

Programa TURI grąžinti šiuos kodus kviečiančiai aplinkai:

0 – sėkminga programos darbo pabaiga;

1 – klaida viename ar keliuose parametrų rinkiniuose;

2 – failo skaitymo ar rašymo klaida;

3 – įvyko matematinė skaičiavimo klaida.

Galimi ir kiti kodai su aukštesniais numeriais. Visi grąžinami statuso
kodai turi būti dokumentuoti programos aprašyme ir komentaruose.

Nuorodos
========

1. S. Bradner "Key words for use in RFCs to Indicate Requirement
   Levels", RFC 2119, URI: https://tools.ietf.org/html/rfc2119

2. Library of Congress. CSV, Comma Separated Values (RFC
   4180). https://www.loc.gov/preservation/digital/formats/fdd/fdd000323.shtml
   [accessed: 2022-04-05T11:50+03:00]

3. Library of Congress. TSV, Tab-Separated
   Values. https://www.loc.gov/preservation/digital/formats/fdd/fdd000533.shtml
   [accessed: 2022-04-05T11:51+03:00]

4. Wikipedia (2025) XYZ file format. URL:
   https://en.wikipedia.org/wiki/XYZ_file_format [accessed:
   2025-02-09T17:01+02:00, permalink:
   https://en.wikipedia.org/w/index.php?title=XYZ_file_format&oldid=1270820839].

Colophon
========

$Id: atomų-generavimo-užduotis.txt 12143 2025-02-10 19:59:03Z saulius $
$Header: file:///home/saulius/svn-repositories/paskaitos/VU/bioinformatika-III/u%C5%BEduotys-praktikai/atom%C5%B3-generavimo-u%C5%BEduotis/tasks/lt/atom%C5%B3-generavimo-u%C5%BEduotis.txt 12143 2025-02-10 19:59:03Z saulius $
$URL: file:///home/saulius/svn-repositories/paskaitos/VU/bioinformatika-III/u%C5%BEduotys-praktikai/atom%C5%B3-generavimo-u%C5%BEduotis/tasks/lt/atom%C5%B3-generavimo-u%C5%BEduotis.txt $