Skip to content

Commit

Permalink
complete readme, arch, test results, test summary
Browse files Browse the repository at this point in the history
  • Loading branch information
koffemaria2u committed Apr 26, 2023
1 parent 34ecdc3 commit d95cb85
Show file tree
Hide file tree
Showing 47 changed files with 9,466 additions and 33 deletions.
119 changes: 98 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,60 @@ by: Kevin Offemaria
The project requirements and relevant information are found in the directory:
[project_reqs](project_reqs).

For the required project submission documents, see dir: [submission_files](submission_files).
- `test_cases_summary.pdf`
- `talk_slides.pptx`
- `video_link.txt`
### Part 2 Submission Files
For the required project submission documents, see dir: [submission_files/part2](submission_files/part2).
- `test_cases_summary_part2.pdf`
- `country-sched-architecture.jpg`
- `talk_slides_part2.pptx`
- `video_link_part2.txt`

For part 1, see [submission_files/part1](submission_files/part1).

## Country Search Scheduler
### State Quality
[Fallout](https://fallout.fandom.com/wiki/Fallout_2) is based on a post-apocalyptic world,
and Electronics as a whole is considered to be it's the most valued produced resource.
Intrinsically, Electronics can be defined as anything from radios, automobiles, firearms, etc.

In terms of the State Quality definition, a country values its happiness according to how much `Electronics` it
currently owns. Therefore, its State Quality measure is the count of the amount of available Electronics.
Since Electronics is a produced resource, there is value in having the necessary raw materials to produce them though
it would still need resources and time to produce them. This continuity of production is counted towards the SQ
score but with a 50% penalty. All of these are reflected in the [resource weights](src/input_files/world_resources_1.csv)
There is a cap on Electronics against the country's population assumed at a 2:1 ratio of Electronics per person.
If a country has more Electronics against its own population, we penalize Electronics, MetallicElements, MetallicAlloys.
This is necessary to shift focus on other resources that may potentially increase population satisfaction
such as `Housing`, which has an increased role in EU contribution. We assume the optimal ratio of persons to a house is
4:1, or 4 persons per single house. A bonus to this resource is applied to incentivize building houses to accommodate
a country's population. However, just like Electronics, once the limit goes above the ratio a penalty will be applied
to discourage building unnecessary houses for a satisfied population.

Finally, there is a small bonus applied to recycling `ElectronicsWaste` due to the scarcity of resources in the
barren wasteland. We assume [~17% of e-waste is recycled](https://www.genevaenvironmentnetwork.org/resources/updates/the-growing-environmental-risks-of-e-waste/) contributing positively to EU score.


[Logistic function](https://en.wikipedia.org/wiki/Logistic_function) constants:
- `x` is the input or independent variable
- `L` is the maximum value of the function
- `k` is the logistic growth rate or steepness of the curve
- `x_0` is the x-value of the sigmoid's midpoint


### Search Algorithm
There are 3 search functions that can be used in the program: Greedy Best First Search, Heuristic Depth First Search,
Breadth First Search. GBFS utilizes the PriorityQueue class from the Python library, queue, as the storage frontier.
While the others use the built-in Python List object. The algorithm of all three functions is generally the same
whereby they start with a root node inserted into the frontier and generate children nodes based on a root
or parent node. It then attempts to generate Action Templates for TRANSFORMs and TRANSFERs.
The resource values for the current node’s country are modified by the Action. The new child nodes are randomly
shuffled and appended to the frontier. Next, the Expected Utility score on the current node is calculated
and evaluated against the best scoring EU node. If so, replace the best EU node with the current node,
and write all the Action Templates for all parent nodes of the current node. The program ends when the maximum depth,
or frontier size has been exceeded, or the frontier is empty. See diagram below.


#### Country Schedule Architecture
![alt text](submission_files/part2/country-sched-architecture.jpg "arch")

## Usage
### Installation
Expand Down Expand Up @@ -42,29 +92,56 @@ python src/country_scheduler.py
--resource-file src/input_files/world_resources_1.csv
--state-file src/input_files/world_state_1.csv
--output-file src/output_files/bfs_results
--num-schedules 10
--depth-bound 10
--frontier-size 5000
--search_type gbfs # choices=["bfs", "hdfs", "gbfs"]
--num-schedules 20
--depth-bound 20
--frontier-size 10000
--loglevel INFO
```

## Around the repo
### Around the repo
1. Test Results are found in the [output_files](src/output_files)
- The last few characters of the file name indicate the test case and iteration (eg. `bfs_res...test1a.txt`)
2. Initial states are found in [input_files](src/input_files)
3. Main program in `src/` dir
- entrypoint: `country_scheduler.py`
4. `submission_files/` contain the summary files as advised the project requirements.

### Directory Structure
```
├── project_reqs
│ ├── Part1
│ ├── Part2
├── src
│ ├── input_files
│ │ ├── world_resources_1.csv
│ │ ├── world_state_1.csv
│ ├── output_files
│ │ ├── result_graphs
│ │ ├── result_plots
│ ├── base_classes.py
│ ├── country_scheduler.py
│ ├── world_search.py
│ ├── util.py
├── submission_files
│ ├── part1
│ ├── part2
├── README.md
├── README_notes.md
├── requirements.txt
└── .gitignore
```

## Presentation Notes
1. At first, I embedded the `ActionTransfer` functions (now a class) into the WorldSearch. But realized it could be too
tightly coupled, and figured I could use this on its own somehow on Part 2 of the project.
2. Adding a hardcoded transfer percentage of up to 20% of resources
- this would cause uneven trades if 1 resource is much higher than the other
- to balance, add a check that resources for transfer shouldn't be > 200% both ways
3. higher COST_OF_FAILURE lead to finding_best nodes in deeper depths
## Citations
Class community citations:
- John Ford – Concept of [Resource decay](https://piazza.com/class/lbpfjbrwi0ca3/post/22)
- Karely Rodriguez – Proper implementation of [HDFS, alpha-beta pruning](https://github.com/karelyrodri/AI_Virtual_World/blob/main/Search_Strategies/HeuristicDepthFirstSearch.py#L34)

### Notes
Logical function variables:
- `x` is the input or independent variable
- `L` is the maximum value of the function
- `k` is the steepness of the curve
- `x_0` is the x-value of the sigmoid's midpoint
Online citations:
- [E-waste recycling](https://www.genevaenvironmentnetwork.org/resources/updates/the-growing-environmental-risks-of-e-waste/)
- [Fallout Random Encounters](https://fallout.fandom.com/wiki/Fallout_2_random_encounters)
- [Greedy Best First Search](https://www.youtube.com/watch?v=dv1m3L6QXWs)
- [Depth First Search](https://www.youtube.com/watch?v=pcKY4hjDrxk&t=730s)
- [Breadth First Search](https://www.youtube.com/watch?v=pcKY4hjDrxk&t=252s)
- [Metals deterioration](https://xapps.xyleminc.com/Crest.Grindex/help/grindex/contents/Metals.htm)
- [Timber decay](https://www.fs.usda.gov/research/treesearch/7717)
155 changes: 155 additions & 0 deletions README_notes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
# Kevin's Notes
### Project Part 1 Feedback
1. Somewhat simplistic state quality function, but I love that you are including recycling to offset the creation of waste

2. You are weighting electronics heavily and then weighting things used to produce electronics slightly less with the
purpose of encoding that we need alloys to create electronics <- this is human intuition that is not needed in AI...
if your "good state" (as determined by your state quality function) involves having lots of electronics, your AI should
automatically find schedules that allow you to produce those electronics

3. If you are implementing Breadth-First Search, then you can't be using a Priority Queue <-
I think you may have implemented Greedy Best-First Search instead.

4. I love your initial state being based on Fallout 2...very creative idea!

5. I like that you include the number of nodes visited as a statistic in your Node ID...neat way to visualize how many
nodes had to be traversed to find a schedule

6. Test 1 Results: You say that in some of the runs, you only reached a depth of 10...do you mean the schedule with the
best EU was FOUND at a depth of 10, or your algorithm only searched to a depth of 10, presumably because your frontier ran out of space?

7. For the next part, I would definitely move away from anything breadth-first related, as (I think you've seen),
the search space gets very large very quickly and doesn't allow you to go very deep to find better solutions.

8. I also see that you are inverting your EU values, presumably because they are negative. If they are negative,
I would debug that calculation, since EU should be positive (and hopefully increasing over time).
- this is incorrect, I'm flipping the values because the PQ's `get()` method returns the lowest value which is what
we want for GBFS implementation


### Project Part 2 Proposal
1. No programmatic improvements are graded. But can if I fix some aspects based on the feedback from part 1,
will that be included in grading part 2? how significantly?
- [x] fix or not use priority queue, for using BFS
- BFS traverses the frontier in the order that you've added items to the frontier FIFO
- a PriorityQueue will always reorder items in the frontier anytime an item is added
- [x] removing human intuition from state quality
- resource weighting influencing agent towards Electronics and its raw materials
- [x] fix EU values in GBFS, inverting negative values
- this is correct, nothing to change
- GBFS selects the node with the HIGHEST heuristic value from the priority queue and expands it, adding its
neighboring nodes to the priority queue in order of their heuristic values
- [video explanation](https://www.youtube.com/watch?v=dv1m3L6QXWs)
- [x] randomize EU evaluation of templates
- [x] add graphs/plots
- [x] 6 test cases
- [x] use NCR; w/ GBFS and HDFS and BFS
- moderate resources,
- high electronics/housing to population ratio (higher state quality to start)
- generally more transfers
- [x] use Arroyo; w/ GBFS and HDFS and BFS
- extremely high resources,
- low electronics/housing to population ratio (lower state quality to start)
- generally more transforms

2. new features:
- [x] NEW FEAT 1
- add more uncertainty on templated actions
- "random encounters" during TRANSFERs, possibly getting hijacked of resources
- [source](https://fallout.fandom.com/wiki/Fallout_2_random_encounters)
- [x] NEW FEAT 2 On Transforms
- [x] Recycling would not only reduce waste, but also increase raw materials by reusing working electronic parts from the waste
- [x] NEW FEAT 3 increase SQ complexity
- [x] if producing more Electronics against country population, penalize Electronics, MetallicElements, MetallicAlloys
- [x] if producing too much Housing against country population, penalize Housing
- [x] NEW FEAT 4 add entropy or decaying of resources
- this would introduce maintenance of Electronics, maybe
- Deterioration rates
- Metals [1% - 5% corrosion rate](https://xapps.xyleminc.com/Crest.Grindex/help/grindex/contents/Metals.htm)
- Timber [20% decay rate](https://www.fs.usda.gov/research/treesearch/7717)
- every 3000 nodes
- [x] NEW FEAT 5 - implement HDFS
- make note of the limitations you are seeing with HDFS and report on your findings
- [x] NEW FEAT 6 - implement BFS

3. deliverables:
- [] TalkSlides.pptx: PowerPoint slides to accompany your video
- [] VideoLink.txt: Text file containing a link to your narrative video (e.g., a private link on YouTube or a link to
a Zoom recording of no more than 15 minutes). The bulk of your Part 2 grade will be based on the video and slides,
with expected content to include:
- [x] A figure and explanation of the comprehensive architectural design of your system,
- [x] A focus on any improvements, additions, changes, or expansions that you made since Part 1,
- [x] Summaries of experimental studies, including explanations of selected test cases, graphs, and tables,
- [x] Comparisons between the results of your Part 1 and Part 2 outputs, including the quality of the resulting
schedules, the speed or efficiency of your algorithms, and the complexity of the resulting outputs,
- [x] Citations to outside sources that you used, including references to other students.
- [] SourceCode.zip: well-documented and well-formatted code, including:
- [x] README: Containing clear and detailed directions for running your code and identifying the file containing the country scheduler function, and any other important top-level functions.
- You will also be graded on the documentation and format of the entirety of Part 1 and Part 2 code.



### Notes for Part 2
1. found bug on func `create_child_nodes()`
- the Transform template was doing unnecessary looping for all countries, but we only care about Transforms of the `self.country = NCR`
- as a result on `evaluate_best_score()`, we only need to evaluate the EU score of our own self country
2. randomize EU evaluation of templates
- remove Electronics as barter resource
3. plot results function
4. stabilize resource weights
5. 6 test cases
6. increase SQ complexity
- if producing more Electronics against country population, penalize Electronics, MetallicElements, MetallicAlloys
- separate calculation
- if producing too much Housing against country population, penalize Housing
7. add random encounters on Transfers
8. add recycle chance on Transforms
9. add plot of EU best scores
10. Fix GBFS, remove BFS
11. Implement HDFS
- w/ reached
- dfs forces the search to go down the leftmost branch whether it's a good schedule or not
- it sets the standard for what is "good" then as it travels slowly to the right
- at the end of each iteration before appending the nodes to the `self.frontier`, I'm sorting the new child nodes in ascending order.
- This forces the next `self.frontier.pop()` to take the last node with highest EU score
12. add resource decay
- i noticed that there are more transfers to keep decay at bay
13. bfs
- calculate EU
- use built-in python list
14. test case 1,
- GBFS,
- -ns 20,
- -d 20,
- -f 10000
- NCR
15. test case 2
- GBFS,
- -ns 20,
- -d 20,
- -f 10000
- Arroyo
16. test case 3,
- HDFS,
- -ns 20,
- -d 5,
- -f 20000
- NCR
17. test case 4,
- HDFS,
- -ns 20,
- -d 5,
- -f 20000
- Arroyo
18. test case 5,
- BFS,
- -ns 20,
- -d 10,
- -f 50000
- NCR
19. test case 6,
- BFS,
- -ns 20,
- -d 10,
- -f 50000
- Arroyo
Binary file added project_reqs/5260_Programming_Project_P2.pdf
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit d95cb85

Please sign in to comment.