TDDD92 AI-projekt

Slutrapporter i TDDD92

När du är klar med ditt arbete i kursen ska två slutliga rapporter lämnas in (deadlines och inlämningstillfällen finns på separat sida):

• En individuell slutrapport, som är en utökning av den individuella utredningsrapporten med nya avsnitt som även täcker det som har gjorts under projektarbetet.

• En kortare gemensam grupprapport, som täcker gemensamma delar i projektarbetet. Denna rapport måste få godkänt för att individerna i gruppen ska kunna få godkänt, så normalt lämnas den in till jul/nyår när kursen slutar. Det räcker med att en gruppmedlem lämnar in den, men hjälps åt att se till att den inte blir bortglömd!

Här beskriver vi i princip hur de idealiska rapporterna skulle se ut. Man kanske inte alltid kan uppnå den perfekta beskrivningen i alla hänseenden, men det visar åt vilket håll man ska sikta.

Fokusera gärna extra mycket på tydlighet och precision i beskrivningar och resonemang. Luddighet och otydlighet är de vanligaste problemen i tidigare års rapporter.

Alla rapporter lämnas in i PDF-format via en issue i Gitlab. Dessa issues kommer att vara konfidentiella och kan enbart ses av inlämnaren + kursledningen. Du ska också göra en separat inlämning till språkgranskning via Lisam:s inlämningssystem.

Fråga om något är oklart!

Syfte

Slutrapporterna har en viktig roll i examinationen för projektmomentet. Givetvis tittar vi även på annat, som t.ex. resultatet av den implementation ni har gjort, men i rapporterna har ni en särskilt bra chans att ge oss mycket av den information vi kan basera betyget på. Det är också i den individuella slutrapporten som ni kan dra vår uppmärksamhet till det ni vill visa upp som en bas för ett högre individuellt betyg på projektet! (Detta kan även gälla sådant som t.ex. redan har diskuterats på seminarier och redovisningstillfällen.)

Se även information om delbetyg och kursbetyg.

Gruppens slutrapport

Gruppens slutrapport ("grupprapporten") ska beskriva arbetet på gruppnivå, och detta kräver typiskt 2-3 sidor information utöver rubrik / författare. Kortare rapporter är oftast inte tillräckligt informativa. Längre rapporter innehåller oftast information som inte behövs. (Som vanligt är det helt OK att lägga till extra många bilder, och då kan rapporten ta upp flera sidor.)

Rapporten är mindre formell än den individuella utredningen / slutrapporten. Vi granskar inte språk och struktur men rapporten måste fortfarande vara tydlig och inte tvetydig eller svårläst. Den ska också följa samma stilmall som den individuella rapporten. Denna kan laddas ner separat tillsammans med en mall för själva texten.

Vi förväntar vi oss följande information i egna rubriksatta avsnitt (lägg gärna till underrubriker men ändra inte på huvudrubrikerna):

• (Titel med kurskod, årtal, samtliga gruppmedlemmar med namn och LiU-ID)

• (Abstract / sammanfattning behövs inte!)

• Inledning: En kort inledning. Här kan ni skriva en inledning, om ni vill. Lämna annars avsnittet tomt, men ta inte bort det (det är bra om vi har samma avsnittsnumrering i alla rapporter).

  Slösa inte tid på att förklara StarCraft i onödan, eller på att beskriva att detta är en rapport i en kurs som har de här specifika kursmålen. Förutsätt att alla som läser rapporten är handledare som redan vet sammanhanget och som bara vill ha klar och tydlig information om det som är specfikt för just ert projekt.

  Men kanske det ändå finns information som ni vill ge läsaren innan ni börjar ge informationen i de övriga avsnitten? I så fall lägger ni det under rubriken "Inledning" i mallen.

• Mål: En beskrivning av det mål gruppen har satt upp. Läsaren är handledare eller examinator och känner redan till det generella målet med kursen! Det vi vill veta är: Har gruppen valt att fokusera mer på vissa av alla de möjligheter som finns inom kursen? har ni profilerat er agent på något särskilt? Har ni valt att inte bry er så mycket om vissa aspekter så mycket (vilket är helt OK med tanke på kursens omfattning)? Varför har ni tillsammans gjort dessa val?

  Även om ni inte har gjort en tydlig struktur för detta från början har ni säkert gjort mer eller mindre medvetna val i fråga om vad ni ser som viktiga delar och vad ni inte satsar på. Det kan vara till hjälp i bedömningen av arbetet.

  Detta avsnitt kan vara relativt kort. Ni behöver inte försöka "uppfinna" mål som ni inte har haft, utan avsnittet ger er en möjlighet att beskriva de fokuseringar som ni eventuellt har gjort.

• Problem och AI-tekniker: En mycket kortfattad punktlista på de individuella AI-tekniker ni har valt att implementera och de problem som teknikerna löser. Detta kan vara på formen "Applicerat FOO-learning tillsammans med XYZ-search för att bestämma var och hur ABC ska utföras". Beskriv också vem eller vilka som har arbetat på detta, och ungefär hur stor andel som var och en har gjort (om det är flera som har arbetat med det).

  Var och en får väldigt mycket mer utrymme att beskriva teknikerna och lösningsmetoderna i de individuella slutrapporterna, så var tydliga men håll det ändå mycket kortfattat. Meningen är att ge läsaren en översikt över hela gruppens arbete och ungefär vilka problem och lösningar som behövde "sys ihop" till en gemensam agent, inte att förstå alla detaljer i varje individs arbete.

• Struktur och integration: En konceptuell beskrivning av den övergripande strukturen hos agenten som har utvecklats.

  Detta handlar alltså inte alls om kod på nivån av funktioner, klasser och källkodsfiler, utan vi vill förstå på en hög nivå hur allt är tänkt att fungera, hur de olika funktionaliteterna (AI och andra) är integrerade, och hur agenten egentligen tar sina beslut. Vi vill också veta om ni har använt den "nya" grundagenten för projektet eller använt er av egen kod som t.ex. har sin grund i labbarna.

  Man kan möjligen använda pseudokod på en mycket hög nivå, men det ska i så fall vara för att beskriva t.ex. en huvudloop där man ser hur de olika gruppmedlemmarnas delar anropas och/eller interagerar. Man får gärna rita enkla diagram som visar hur delar hänger ihop.

  Några exempel på frågor som kan besvaras av rapporten: Hur "drivs" agerandet framåt så att agenten faktiskt gör något? Hur och av vem används / anropas de olika individuella funktionaliteterna? Hur är alla funktionaliteter "kopplade" till varandra, hur interagerar de? "Vem" tar olika beslut? Hur och var skapas, hanteras och används olika sorters information?

  För att vara konkret: Det finns kanske en lösning på problemet att hitta en säker väg; vem anropar den och när/varför? Det finns kanske en funktionalitet som försöker att hela tiden utforska världen; hur ser man till att den hela tiden körs, och vem använder utdata?

  Diagram är som sagt mycket välkomna som en del i förklaringarna och rekommenderas starkt. De behöver inte vara vackra men måste vara tydliga.

  När man har läst beskrivningen ska man förstå, på en hög abstraktionsnivå, att "aha, det är så agenten jobbar när den gör det jag ser i demonstrationen". Detta är bland annat kopplat till kursmålet att integrera AI-tekniker i system. En direkt koppling till olika funktioner, klasser, filer och andra implementationsdetaljer är inte önskvärd.

• Resultat och slutsatser: Hur gick det, och vilka slutsatser kan man dra kring resultatet? Detta gäller alltså helheten, medan de enskilda teknikerna främst kan utvärderas i de individuella delarna av rapporten.

  Exempel på frågor att dra slutsatser om: Vad har vår agent för styrkor och svagheter? Varifrån kommer dessa styrkor och svagheter? Vad hade kunnat krävas för att slå den inbyggda motståndaren på nästa svårighetsnivå? Hur gick det i tävlingar mot andra agenter (inbyggda och andra gruppers agenter), och varför (styrkor och svagheter)? Vad hade gruppen gjort annorlunda (främst i fråga om struktur och lösningar) om man påbörjade projektet idag med de kunskaper man har fått?

  Tänk på att motivera slutsatserna och kom ihåg att våra frågor bara är exempel för er inspiration, inte ett frågeformulär. Kom gärna på egna frågor.

Gruppmedlemmar som inte är färdiga med sitt individuella arbete bör ändå bidra till grupprapporten, som då ska beskriva vilka delar som inte är avslutade och hur långt man ändå har kommit med dem. Medlemmen som inte var helt färdig när rapporten skrevs lämnar sedan också in en uppdaterad grupprapport (där de egna delarna är uppdaterade) tillsammans med sin individuella slutrapport när den är färdig.

Om någon medlem inte alls kan bidra till den ursprungliga grupprapporten får övriga medlemmar diskutera detta med examinatorn, så får vi komma fram till hur vi hanterar detta i det specifika fallet. Detta kommer i vilket fall som helst inte att hindra er att lämna in en grupprapport för de som är färdiga.

Den individuella slutrapporten

Den individuella slutrapporten är alltså en utökning av den ursprungliga utredningsrapporten.

• Individuell slutrapport består av:
  • Del 1: Individuell utredningsrapport
  • Del 2: Individuell projektrapport (utökningen)

När du gör denna utökning och lägger till projektrapporten i slutet ska du också:

• Ändra filnamn från Utredning-TDDD92-2021-liuid123 till Slutrapport-TDDD92-2021-liuid123

• Ändra titel så att den innehåller ordet "slutrapport".

Utredningsdelen

I utredningsdelen av slutrapporten förväntar vi oss att du har tagit hänsyn till den återkoppling du har fått efter din första inlämning, både språkligt och i fråga om själva utredningen, och att du har uppdaterat rapporten enligt detta.

Om du har kommit till nya teoretiska slutsatser, t.ex. om hur olika AI-tekniker fungerar, får du gärna uppdatera utredningen med de slutsatserna. Men tänk på att du inte ska uppdatera utredningsdelen med dina praktiska experimentella slutsatser som du har fått från själva implementationen. Den teoretiska utredningen kanske ledde dig till att tro att teknik A skulle vara bäst, medan du sedan insåg att det faktiskt var teknik B som fungerade bättre när du väl fick en möjlighet att experimentera med implementationen. Då varken behöver eller ska du uppdatera utredningen med den informationen. Den teoretiska utredningen ska fortfarande utgå från den information som du kunde få från de artiklar som du läste, inte från ditt eget praktiska arbete.

Vid större förändringar i problem eller teknikval

Har du bytt teknik? Om du först drog slutsatsen att du skulle implementera en viss teknik, men sedan har bytt till en annan av de tekniker som du jämförde i den ursprungliga rapporten, är det inga problem. Om du byter till en helt ny teknik kan du ha kvar din ursprungliga beskrivning, men du behöver sedan beskriva den helt nya tekniken i den avslutande projektdelen av rapporten. Du kan då använda extra utrymme för den beskrivningen. Fråga om något är oklart!

Fråga också om du har bytt problemställning eller gjort andra ändringar med större påverkan på din utredningsdel. I princip behöver du se till att det nya förklaras tillräckligt väl; vi behöver t.ex. få en beskrivning av nya tekniker eller nya sätt att modellera så vi kan utvärdera utifrån de teknikerna. Diskutera detta med oss så vi kan komma fram till hur du kan göra det utan att lägga ner onödigt mycket nytt arbete. Skapa gärna en issue med information kring vad som har förändrats under höstens gång så utgår vi från det i vår diskussion.

Projektrapporten: När du fortsätter enligt den ursprungliga planen

Givet att du fortsätter enligt den ursprungliga planen från utredningsrapporten vet vi redan vilket problem och vilken teknik du ska använda. Utredningsdelen innehåller också en del information om modellering med mera. Då ska du utöka din rapport med fokus på följande information, som kan se omfattande ut men normalt ska få plats på cirka 2-3 sidor:

• Faktisk användning i StarCraft II: Hur har du faktiskt applicerat dessa tekniker i StarCraft? Detta är en viktig del av betygsunderlaget!

  Du har redan beskrivit hur du tänkte modellera problemet i StarCraft, mer eller mindre. Nu har du faktiskt genomfört modelleringen och du har mer konkret information om hur modellen blev. Låt den ursprungliga sektionen om användning av StarCraft II vara kvar i den första delen av rapporten, och lägg till den nya sektionen Faktisk användning i StarCraft II i den nya delen av rapporten.

  Här bör du beskriva hur du faktiskt modellerade problemet för att den valda tekniken ska lösa relevanta problem i StarCraft-världen. Till exempel kan detta inkludera:

  • Val eller utveckling av features vid maskininlärning

  • Vilka variabler och nätstrukturer som användes eller lärdes in för Bayesianska nätverk

  • Exakt vilken tillståndsrymd som användes för en sökalgoritm. Vad är rotnoden? Vilka noder finns? Mellan vilka noder finns det bågar? Vilka barn finns till en nod? Exakt hur beräknas en bågkostnad? Exakt hur beräknas en heuristik?

  • Om du använder potentialfält, vad motsvarar potentialerna? Exakt hur definieras potentialens avtrappning från en punkt? När räknas potentialerna om? Vilken upplösning används i rutnätet? Exakt hur använder du potentialfältet för att ta beslut (t.ex. som bågkostnad i sökning, eller andra metoder för att välja nästa punkt att gå till)?

  • Om du har använt maskininlärning, vad har du använt för grunddata för inlärningen? Vilka features har du baserat inlärningen på (vid vissa typer av inlärning)? Hur har inlärningen gått till? Vad blev resultatet? Vid Q-learning, vilka tillståndsstrukturer användes, vilka belöningar gavs, vilka vilken policy blev resultatet? Vid inlärning med Bayesianska nätverk, vad blev de inlärda sannolikheterna?

  • Om du har delat upp kartor i regioner, finns det några parametrar du har valt på ett speciellt sätt?

  • Om du har använt replays eller andra data, tala då om både var de kommer från och vilka replays du har använt. (Om detta tar mycket plats går det bra att ta extra sidor till en tabell på slutet.)

  • ...och så vidare.

  Nu har du alla detaljer. Beskriv dem tillräckligt tydligt och precist! Intuitioner är också viktiga, men vi är inte ute efter en ungefärlig beskrivning för att kunna se att "det låter väl rätt rimligt att göra ungefär så här". Vi är snarare ute efter att:

  • Förstå i detalj vad du har gjort och varför resultaten blev som de blev. Det behövs precision i informationen för att kunna analysera och förstå anledningarna till ett resultat, t.ex. analysera varför maskininlärningen tog så lång tid – eller avgöra om dina slutsatser om resultatet verkar rimliga. Samma sak gäller att förstå exakt vad det var som egentligen fungerade.

  • Åtminstone i teorin kunna upprepa det du gjorde genom att följa dina instruktioner! Reproducibility is a major principle underpinning the scientific method. With a narrower scope, reproducibility has been introduced in computational sciences: Any results should be documented by making all data and code available in such a way that the computations can be executed again with identical results. [Wikipedia] Vi kommer inte att nå riktigt ända dit, men ha den tanken i bakhuvudet. Exempel: Istället för att beskriva ungefär vad en heuristik baseras på, beskriv den exakta formeln.

  Om du har undersökt andra alternativ för hur du kunde ha applicerat en lösningsmetod bör det också framgå, speciellt om du faktiskt har utvärderat de olika alternativen. Om du har fått delar av modelleringen från en StarCraft-artikel, istället för att välja och utveckla en modellering själv utifrån en generell funktionalitet (såsom A* som är mycket generell), ska detta framgå tydligt.

  Var noga med att tala om vad resultatet blir. Exempel: Om du arbetar med byggnadsordning, talar du då om vad som ska byggas i nästa steg, eller vad som ska byggas i flera steg framåt? Eller talar du inte bara om vad som ska byggas, utan ser även till att det faktiskt blir byggt?

  Diagram och figurer kan vara mycket användbara för att förklara och är starkt rekommenderade.

  Det är fullt tillåtet att återanvända en del text från det ursprungliga avsnittet om användning i StarCraft, så länge som den uppdateras med det du har gjort under andra kursperioden. Diskutera gärna också om dina inledande idéer fungerade eller om/varför/hur du har behövt tänka om / modellera om efter dina praktiska erfarenheter!

• Kopplingar: En beskrivning av kopplingar till den övriga implementationen. Detta är viktigt då implementation och integration ingår i kursmålen!

  Är din implementation (alternativt dess in/utdata) mer eller mindre tätt kopplad till andra tekniker eller andra gruppmedlemmars individuella arbete? I så fall, hur? Vilka data får du från vem? Vilken information ger du till vem? Eller är den i princip fristående från övriga specifika AI-tekniker?

  Hur är den i övrigt inkopplad i agenten som en helhet, så att den faktiskt används när agenten spelar?

  Notera att "hur" är tänkt att tolkas på en högre abstraktionsnivå. Vi är inte intresserade av vilka Python-funktioner som anropar varandra, utan av hur teknikerna fungerar ihop, hur de hjälper varandra, hur de beror på varandra, vilken sorts information de ger och får – eller som ett alternativ, hur och varför de kan användas helt oberoende av varandra utan att den ena behöver känna till den andra. Ett enkelt diagram kan ofta vara bra för förståelsen.

  En övergripande beskrivning finns i gruppdelen, men där är fokus på helheten, så att säga. Här får du lite mer plats att diskutera just din egen integrering.

  Diskutera gärna hur integration och "inkoppling av funktionaliteterna" har påverkat ditt arbete. Finns det till exempel ytterligare krav som ställs på din teknik för att integrationen ska fungera? Har förenklingar skett genom att fler personer kan dela på implementerad funktionalitet?

• Resultat: En beskrivning, analys och utvärdering av resultatet för just din specifika AI-teknik.

  Detta är också en mycket viktig del: Att kunna utvärdera tekniska lösningar är ett av de uttryckliga kursmålen som måste examineras! Tänk också på att inte bara ge subjektiva värderingar utan fokusera på en motiverad och objektiv bedömning av det tekniska resultatet.

  Utvärderingen kan inkludera jämförelser mellan olika tekniker eller handla om resultatet när man applicerade en specifik teknik. Vad blev resultatet när du applicerade din teknik i StarCraft? Blev det bättre eller sämre när din funktionalitet aktiverades, jämfört med om man körde agenten utan din funktionalitet? Hur mycket, på vilket sätt, varför?

  Vi pratar alltså om resultatet för agenten. Det handlar alltså inte bara om att t.ex. "byggnadsordningen blev annorlunda", även om det också är intressant att se detta (och på vilket sätt den blev annorlunda). Det vi är ute efter i projektet är en agent som spelar StarCraft II på ett bra sätt, och frågan är alltså på vilket sätt den valda tekniken bidrog till att nå närmare detta mål. "I och med att vi bygger i en bättre ordning händer X och det hjälper oss mot fienden genom Y".

  Den huvudsakliga meningen med detta avsnitt är inte att motivera varför den egna lösningen är bra. Vi fokuserar inte på "prestationen", eftersom vi är medvetna om att kurstiden inte alltid räcker för att man ska uppnå den perfekta implementationen, och mycket kan hända som man inte har kontroll över. Det handlar mer om att analysera varför den allmänna tekniken och den specifika implementationen gav vissa resultat, än om att analysera varför man själv kom dit man kom.

  Det handlar inte heller om att man måste motivera varför det egna arbetet gjorde att agenten spelade mycket bättre. Det kan hända att det inte alls blev bättre. Beskriv detta och utvärdera varför det blev som det blev!

  När vi säger "hur mycket, på vilket sätt, varför?" menar vi också att vi vill se tydliga beskrivningar av resultaten och hur de yttrade sig i spelet. Går det att se hur mycket oftare man vinner? "Lite oftare", är det 10% oftare eller 50% oftare? Ofta går det att beskriva mer kring skillnaderna: "förut gjorde den så här men med den nya tekniken beter den sig så här istället"... med en del detaljer som gör att man förstår det hela, och varför det inträffar. Det handlar alltså inte bara om en allmän slutsats om att "det gick väl bra", utan om att visa hur man uppfyller lärandemålet att kunna utvärdera AI-tekniker och hur de påverkar ett system.

  Vissa kanske också har delresultat att rapportera: Gör man på sätt A blir resultatet X, gör man på sätt B blir resultatet Y. Varför blev det så?

• Slutsatser kring AI-tekniker: Individuella slutsatser kring ditt arbete med AI-tekniker i projektet. Hur svårt var det att applicera en viss teknik? Gick det som du förväntade dig?

• Insatser i gemensamt arbete: En kort beskrivning / sammanfattning av vad du har gjort i den gemensamma implementationen och ungefär hur stor del av tiden du har lagt på den aspekten av agenten.

• Övrigt: Om du vill kan du även ta upp annat som du tycker kan vara relevant för bedömningen av hur du har uppnått kursens lärandemål.

Det går utmärkt att lägga in nya underavsnitt för att dela upp de existerande avsnitten. I övrigt ska rapporten följa den struktur som ges ovan.

Tyngdpunkten i den individuella delen ska vara på det du själv har gjort inom dessa områden (modellering, utvärdering, eventuell algoritmutveckling, med mera). Ju mer du har fått från en artikel, desto större tyngd behöver läggas på andra områden. Har man till exempel fått både algoritm och modellering från en StarCraft-specifik artikel behöver man lägga extra mycket arbete på utvärderingen.

Ärliga och opartiska bedömningar!

Det är viktigt att göra en ärlig utvärdering i rapporterna.

Vi väntar oss inte att alla har valt den bästa tekniken redan från början, eller att alla har hunnit göra den perfekta implementationen. En viss miniminivå är visserligen nödvändig enligt kursmålen, men kursen har alltför begränsad tid för att man ska hinna med allt det man hade velat göra. Man ska alltså inte känna att man behöver skönmåla resultatet för att det ska bli godkänt.

Tvärtom är det mycket viktigare att visa insikter om hur det egentligen gick. Detta är en viktig del av kursmålen -- att kunna utvärdera. Det kan man göra genom att tydligt utvärdera t.ex. vilka försök som fungerade bra och vilka som inte fungerade bra (kanske AI-tekniken inte var lämplig trots allt?), och motivera varför det var så. Precis som i den individuella utredningen är det också viktigt att dra lagom starka slutsatser -- inte för svaga men inte heller starkare än vad man kan ge tydliga motiveringar för.

Hur formell är slutrapporten?

De nya delarna av slutrapporten är mindre formella än den del som gäller den individuella utredningen, på så sätt att de nya delarna inte ska språk- och strukturgranskas. Det är helt enkelt en rapport över era projektresultat.

Tänk ändå på att det ska vara klart och tydligt vad ni menar med det ni skriver, och att det ska framgå vad ni har gjort i projektet. Återigen: Detta är en av era viktigaste möjligheter att visa upp era kunskaper och framsteg, vilket ni på ett eller annat sätt behöver visa oss för att vi ska kunna motivera ett godkännande eller ett högre betyg.

Precis som i utredningsdelen behöver man inte beskriva allmänna egenskaper hos StarCraft, eller det allmänna syftet med grupparbetet i TDDD92, då detta kan antas vara känt av läsaren (examinatorn och handledarna). Det går så klart bra att beskriva specifika delar av StarCraft som man vill koppla sina resonemang till!

Inlämning av kod

Deadlines, plussning och komplettering

Deadlines finns på separat sida.

Plussning är möjlig vid inlämningstillfällena i mars/april och augusti. När nästa års kursomgång börjar finns ingen garanti att plussning kommer att fortsätta vara möjlig, eftersom kursens innehåll ständigt uppdateras och justeras. (På en tenta kan plussning vara möjlig under lång tid eftersom det då är upp till studenten att hålla sig uppdaterad med det nya kursinnehållet och ta den nya tentan så som den ser ut efter att kursen har förändrats. För den här kursen skulle det motsvara att genomföra hela projektet från början så som det ser ut efter att kursen har förändrats.)

Komplettering kan också kräva mer arbete när nästa kursomgång har börjat; se slutet av deadlinesidan.