OHJ-2550 Tekoäly - kevät 2007

Harjoitustyö 3: Texas hold'em

Muutoksia:
11.4.2007 Harjoitustyöohjeen ensimmäinen versio.
27.4.2007 Lisätty että tiedostoissa voi pitää tietoa turnausten välillä.
4.5.2007 poistettu kohta jonka mukaan tämä dokumentti voi muuttua :) Pelaajalletieto-structiin on myös lisätty kentät omakorotus ja omapottiin.
7.5.2007 Lisätty että turnaus -ohjelmalle voi antaa parametrina montako kertaa se ajaa saman turnauksen ja että ohjelman logi kirjoitetaan PELILOGI.txt:hen.
7.5.2007 simulaattorista on nyt versio, joka laskee tasatilanteessa oikeat voitot. Aikaisemmin jos oli kaksi voittajaa, panostaneet 3000 ja 1000, niin potti jakautui 2000-2000.
8.5.2007 simulaattorista on korjattu väärin laskettu värisuoran arvo. 10.5.2007 simulaattorissa on nyt Pelaaja-luokassa virtuaalinen funktio turnausalkaa, jonka saa yliajaa, jos tahtoo.
18.5.2007 tiedoksi: voitte käyttää ohjelmaa "ar" yhdistämään useita objektitiedostoja yhdeksi .o-tiedostoksi.
18.5.2007 Selostuksen voi palauttaa paperilla vasta maanantaina, koska laitoksen ovet ovat sunnuntaina lukossa.
18.5.2007 Joidenkin töihin tämä tieto saattaa vaikuttaa eli vastaus kyselyihin, missä työt testataan on, että turnauskilpailu ajetaan Linuxissa.

Kurssin OHJ-2550 kolmas harjoitustyö on Texas hold'em -pokeripeliä annetun rajapinnan kautta pelaavan agentin toteuttaminen. Työ ei ole parityö. Pelin säännöt voi lukea Internetistä, mutta joitain tarkennuksia on kuitenkin annettu. Tehtävänä on toteuttaa ainoastaan peliä pelaava agentti. Agenttia käyttävä pelisimulaattori on valmiiksi toteutettu. Agentin käyttämistä tekoälytekniikoista tulee tehdä lisäksi lyhyt selostus.

Pelin säännöt

Texas hold'emin säännöt löytyvät mm. Wikipediasta ja Pokerikerhon sivuilta. Agenteille järjestettävästä turnauksesta voit lukea tarkemmin vaatimuksista.

Tarkennuksia pelattaviin peleihin:

Valmiina annetut luokat

Vaatimukset

Tehtävänä on kirjoittaa Texas hold'emia pelaava agentti. Jotta agentteja voitaisiin peluuttaa vastakkain tätä varten rakennetussa testipenkissä, tulee agentin toteutuskielen olla ANSI-standardin mukainen C++. Standard Libraryn valmiita tietorakenteita ja algoritmeja saa tässä harjoitustyössä käyttää täysin vapaasti. Agentti kirjoitetaan luokaksi, joka periytetään tiedostossa ~ai/texasholdem/Pelaaja.h annetusta abstraktista kantaluokasta. Luokan nimen on ehdottomasti oltava muotoa t123456, jossa t-kirjaimen perään on laitettu oma opiskelijanumero. Nimiavaruuksien yhteentörmäysten välttämiseksi kaiken opiskelijan tekemän toteutuksen tulee olla joko edellämainitun luokan tai vaihtoehtoisesti opiskelijan oman nimiavaruuden sisällä. Nimiavaruuden nimen on vastaavasti oltava muotoa n123456. Luokka t123456 tulee sijoittaa hakemistoon t123456 ja nimiavaruuden n123456 sisällä oleva toteutus tulee vastaavasti sijoittaa hakemistoon n123456, joka on hakemiston t123456 sisällä.

Agentin pelaajanimeksi tulee asettaa Opiskelijan_oma_nimi/Lintulan_tunnus/Opiskelijanumero eli esim. Teemu Teekkarin agentin nimi olisi "TeemuTeekkari/tteekkar/123456".

Palautuksessa tulee olla myös makefile, joka tuottaa palautetuista tiedostoista objektitiedoston t123456.o komennolla make (missä 123456 on opiskelijanumero). Sanomattakin selvää lienee, ettei ohjelma saa rikkoa pelin sääntöjä tai kaatua kesken kaiken.

Mitä saa tehdä ja mitä ei saa tehdä?

Tämä kohta päivittyy sitämukaa, kun opiskelijat esittävät kysymyksiä. Jos epäilet, että jotain asiaa ei saisi käyttää, niin kysy assistenteilta ennen kuin käytät.

Sallittua:

Kiellettyä:

Minimivaatimukset

Agentti katsotaan riittävän hyväksi, mikäli se voittaa varsin yksinkertaisesti pelaavan agentin Tyhmapelaaja riittävän usein eli vastustajan rahat pitää saada loppumaan vähintään 50% kaksinpeliturnauksista. Eli esimerkiksi, jos agentit pelaavat toisiaan vastaan 100 turnausta, niin vähintään 50:ssä turnauksessa Tyhmapelaaja häviää. Pidätämme itsellämme kuitenkin oikeuden hylätä agentit, jotka on selvästi räätälöity käyttämään hyväkseen Tyhmapelaajan heikkouksia, eivätkä alkuunkaan pärjää muita agentteja vastaan. Agentit eivät myöskään saa pohdiskella siirtojaan kohtuuttoman kauaa. Tämä tarkoittaa, että agentin pitää tosiaan voittaa järjellisessä ajassa.

Läpipääsyvaatimuksena on myös, että agentti ei saa tehdä laittomia panostuksia eli se ei saa tarjota rahaa enemmän kuin sillä on käytössä tai vähemmän kuin on pakko laittaa jne. Simulaattori huolehtii, että laittomuuksia ei tehdä eli turnaus keskeytetään, jos joku agenteista yritti tehdä sääntöjen vastaisen panostuksen.

Tehokkuus

Agentti ei saa kuluttaa kohtuuttomasti aikaa miettiessään seuraavaa liikettään. Maksimiminuuttimäärää ei määritellä, mutta jos joku agentti jää selvästi pohtimaan pitemmäksi aikaa, niin vastausta ei jäädä odottamaan, vaan hidas agentti poistetaan turnauksesta. Kohtuuttomana voidaan pitää, että agentin vastauksen antaminen kestää yli 10 sekuntia. Tämä ei tarkoita sitä, että nyt kaikkien agentit käyttävät 10 sekuntia jokaisen vastauksen antamiseen. Jos näin käy, niin nopeat agentit voidaan palkita lisäpisteillä. Panosta siis agenttisi tehokkuuteen.

Turnauskilpailu

Läpi menneet työt arvostellaan järjestämällä niiden välille turnauskilpailu (ks. Pisteytys-kohta alempaa). Jokainen agentti pelaa useamman turnauksen, todennäköisesti satoja, ellei jopa tuhansia. Sääntöjä rikkova agentti hylättään. Agentilla on jokaisen turnauksen alussa rahaa 1000 euroa. Agenttien täytyy siis toimia järkevästi, virheettömästi ja järkevässä ajassa myös muita kuin Tyhmapelaajaa vastaan pelattaessa. Simulaattorin tiedostossa Apufunktiot.cc löytyvät viimeiset mm. tiedot turnauksen blindirakenteesta ja aloitusrahoista.

Ohjelmointityyli

Palautettavien kooditiedostojen tulee noudattaa hyvää ohjelmointityyliä ja olla asianmukaisesti kommentoidut. Lopullista pistemääräänsä saa alennettua myös kirjoittamalla kehnosti jäsenneltyä, kommentoimatonta ja lukukelvotonta koodia, mutta toisaalta pistemääräänsä voi myös hieman parantaa tekemällä assistentin lukuelämyksen mahdollisimman miellyttäväksi.

Simulaattori

Pelisimulaattori, jolla agentteja tullaan testaamaan ja jolla olisi itsekin syytä hieman testata, löytyy Lintulan hakemistosta ~ai/texasholdem. Lopulta kaikkien agenttien pitää toimia Lintulassa, mutta jos joku haluaa kehittää omassa ympäristössään, niin simulaattorin lähdekoodikin on samassa hakemistossa. Sieltä erityisen koodausmieliset voivat myös kaivaa pelin kulun formaalisti.

Simulaattori käyttää 2-8:aa Pelaaja-luokasta periytettyä (eri) luokkaa. Texas hold'em -turnaus loppuu, kun yhdellä pelaajalla on kaikki rahat ja muilla ei ole euroakaan. Pelien loputtua simulaattori ilmoittaa käyttäjälle pelin lopputuloksen.

Simulaattorin luonti tapahtuu teeturnaus-skriptillä, joka ottaa parametreinaan luokkien nimet. Teeturnaus pitää ajaa hakemistossa, jonka alihakemistoissa ovat annettujen luokkien lähdekoodi ja Makefile ja näiden hakemistojen pitää olla samannimisiä kuin niissä olevat luokat. Tuloksena syntyy ohjelma turnaus. Esimerkiksi ~ai/texasholdem hakemiston public_texas on tehty ajamalla tässä hakemistossa teeturnaus Kayttajapelaaja Jussi Tyhmapelaaja 5, joka luo agentin nimeltä Jussi, joka on luokkaa Kayttajapelaaja, ja viisi tietokonepelaajaa. Luokka Kayttajapelaaja on erikoisluokka, joka kysyy komentoriviltä, mitä tehdään. Yleisesti ottaen teeturnaus-skripti ottaa parametrikseen parin jossa ensimmäinen merkkijono on luokan nimi ja toinen on numero, joka kertoo montako tällaista luokan instanssia käännetään turnaukseen mukaan. Kayttajapelaaja on ainoa poikkeus tässä ja sille se toinen merkkijono on sen nimi. Ohjelmalle turnaus voi antaa parametrina että montako turnausta se ajaa. Tätä ominaisuutta voi käyttää esimerkiksi oman agentin testaamiseen. Ohjelman suorituksen jälkeen pelilogi kirjoitetaan PELILOGI.txt:hen.

Selostus

Harjoitustyöstä täytyy koodin lisäksi tehdä lyhyt selostus. Harjoitustyöselostuksen ideana on selventää toteutetun ohjelman toimintaa ja toiminnallisuuden suunnittelun kulkua harjoitustyön arvosteleville henkilöille. Työselostus on osa harjoitustyön arvostelua. Selostuksen tarkoituksena on myös saada opiskelijat suunnittelemaan työnsä huolellisesti, sillä käsiteltävät kokonaisuudet ovat melko monimutkaisia. Harjoitustyöselostuksen ideana on selventää toteutetun ohjelman toimintaa ja toiminnallisuuden suunnittelun kulkua harjoitustyön arvosteleville henkilöille. Työselostus on osa harjoitustyön arvostelua. Selostuksen tarkoituksena on myös saada opiskelijat suunnittelemaan työnsä huolellisesti, sillä käsiteltävät kokonaisuudet ovat melko monimutkaisia. Työn luonne mahdollistaa monia erilaisia ratkaisutapoja ongelmaan ja koodin määrä saattaa paisua melko suureksi, joten selostuksella on erittäin suuri merkitys.

Selostuksen sisältö

Harjoitustyön selostuksessa tulee käsitellä ainakin seuraavat kohdat:

Havainnollistavien kuvien käyttö työselostuksessa on suositeltavaa.

Selostuksen palauttaminen

Selostus palautetaan määräaikaan mennessä BOSS:iin koodien mukana PDF- tai PS-muodossa JA paperilla laatikkoon #214, joka sijaitsee Ohjelmistotekniikan laitoksen toisessa kerroksessa C-käytävällä.

Yleisiä ongelmia

Agenttitöiden yleisin hylkäämiseen johtava syy on ollut, että agentin koodi ei käänny testitilanteessa.

Palautus

Itse palautus tapahtuu BOSS:n avulla. BOSS ei tee tässäkään työssä minkäänlaisia tarkastuksia, joten testaa ohjelmaasi itse ennen kuin palautat. Työt menevät tarkastusjonoon suoraan eikä palautusten määrää ole rajoitettu. Mutta jos teet uuden palautuksen, niin vanha työsi korvaantuu uudella ja palautus siirtyy tarkastusjonon loppupäähän. Huomioi myös, että jos työsi on otettu jo tarkistukseen, niin vanha työ ei välttämättä korvaudu uudella palautuksella. Palauta työsi siis vasta, kun se on tarkistuskelpoisessa kunnossa, koska palautettuja töitä tarkistetaan jo ennen viimeistä palautuspäivää. BOSS ottaa agenttitöitä vastaan komennolla:

~boss/bin/submit tekoaly agentti texas t123456.zip selostus.pdf

Voit palauttaa niin monta tiedostoa kuin haluat joko luettelemalla jokaisen tiedoston erikseen tai käyttämällä jokerimerkkejä normaaliin tapaan (*.cc jne.). Jos palautat paketoituja tiedostoja, niin käytä paketointiin zippiä. Huom! Jos teet hakemiston n123456, sen voi palauttaa ainoastaan paketoimalla ko. hakemisto ja sen tiedostot yhteen pakettiin. Helpoimmalla pääset, kun paketoit t123456-hakemiston ja palautat vain yhden paketin sekä selostuksen.

Boss lähettää työsi vastaanotettuaan sähköpostia Lintulan tunnuksellesi. Kun työsi on tarkastettu, saat Bossilta jälleen lintulan osoitteeseesi sähköpostia, jossa on saamasi pisteet ja palaute. Pisteitä työstä saa 0-8, vaikka Boss-palautteessa lukeekin esim. kahdeksan pisteen tapauksessa "8/10".

Pisteytys

Tästä harjoitustyöstä voi saada 0-8 pistettä. Läpipääsyyn vaaditaan vähintään yksi piste. Harjoitustyö on pakollinen osasuoritus kurssia, joten kokonaissuoritukseen vaaditaan, että tämäkin harjoitustyö on hyväksytysti tehty.

Toimivasta annetun agentin voittavasta harjoitustyöstä saa 2 peruspistettä. Loput pisteet jaetaan agenttien välille muodostetun turnauskilpailun tuloksista. Eli täysiin pisteisiin vaaditaan, että agentti pelaa Texas hold'emia hyvällä menestyksellä myös muita kuin annettua agenttia vastaan. Turnauksesta poistaminen aiemmin mainittujen syiden takia tuottaa nolla pistettä. Turnauskilpailussa agentit saavat 2-6 pistettä peruspisteiden päälle. Pisterajat määräytyvät sen mukaan, kuinka pieniä piste-erot ovat. Useampi työ tulee saamaan 6 pistettä. Jos tulokset ovat tasaisia, niin kaikki saavat enemmän kuin kaksi pistettä. Esimerkiksi jos pelataan 8 pelaajan pöytäturnauksia, niin voittaja voisi saada kolme turnauspistettä, toiseksi tullut kaksi ja kolmas yhden. Kaikkien turnauksien jälkeen näiden turnauspisteiden summan perusteella sitten lasketaan harjoitustyön saamat lisäpisteet.

Muista, että tyylilliset seikat voivat pienentää edellä mainittuja pisteitä.

Simulaattorista vastaa Jussi eli sitä koskevat kysymykset voi lähettää hänelle. Tehtävänantoa ja pisteytystä koskevat kysymykset voi lähettää Heidille, joka myös tarkistaa työt.