Skip to content

Commit cebb138

Browse files
dav-sonndav-sonn
committed
Small corrections in some documentation files
1 parent 8b227f4 commit cebb138

2 files changed

Lines changed: 139 additions & 137 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,146 +1,11 @@
11
# SimPaths
22

3-
by Matteo Richiardi, Patryk Bronka, Justin van de Ven
3+
by CeMPA (Centre for Microsimulation and Policy Analysis).
44

55
## What is SimPaths and how to use it?
66

77
SimPaths is an open-source framework for modelling individual and household life course events across multiple domains. The framework projects life histories over time, developing detailed representations of career paths, family and intergenerational relationships, health, and financial circumstances. As a family of models, SimPaths offers a dynamic simulation of how life events evolve and interact within populations.
88

99
SimPaths models currently exist for the UK, Greece, Hungary, Italy, and Poland. This page refers to the UK model; the other European models are available at the corresponding [SimPathsEU](https://github.com/centreformicrosimulation/SimPathsEU) page.
1010

11-
The entire SimPaths documentation is available on its [website](https://centreformicrosimulation.github.io/SimPaths/), which includes: a detailed description of its building blocks; instructions on how to set up and run the model; information about contributing to the model's development.
12-
13-
## Quick start
14-
15-
### Prerequisites
16-
17-
- Java 19
18-
- Maven 3.8+
19-
- Optional IDE: IntelliJ IDEA (import as a Maven project)
20-
21-
### Build and run
22-
23-
```bash
24-
mvn clean package
25-
java -jar multirun.jar -DBSetup
26-
java -jar multirun.jar
27-
```
28-
29-
The first command builds the JARs. The second creates the H2 donor database from the input data. The third runs the simulation using `default.yml`.
30-
31-
To use a different config file:
32-
33-
```bash
34-
java -jar multirun.jar -config my_run.yml
35-
```
36-
37-
For configuration options, see the annotated `config/default.yml`. For the data pipeline and further reference, see [`documentation/`](documentation/README.md).
38-
39-
<!-- Projections for a workhorse model parameterised to the UK context are reported in [Bronka, P. et al. (2023). *SimPaths: an open-source microsimulation model for life course analysis* (No. CEMPA6/23), Centre for Microsimulation and Policy Analysis at the Institute for Social and Economic Research*](https://www.microsimulation.ac.uk/publications/publication-557738/), which closely reflect observed data throughout a 10-year validation window. -->
40-
41-
42-
<!--
43-
## Getting Started
44-
45-
To contribute to this project, you need to fork the repository and set up your development environment.
46-
47-
### Access to Data
48-
49-
We are committed to maintaining transparency and open-source principles in this project. All the code, documentation, and resources related to our project are available on GitHub for you to explore, use, and contribute to.
50-
51-
The data used by this project is not freely shareable. If you are interested in accessing the data necessary to run the simulation, get in touch with the repository maintainers for further instructions.
52-
53-
However, please note that _training_ data is provided. It allows the simulation to be run and developed, but results obtained on the basis of the training dataset should not be interpreted, except for the purpose of training and development.
54-
55-
**How to Request Access to Data:**
56-
57-
If you have a need for the data, please contact the repository maintainers through the [issue tracker](https://github.com/centreformicrosimulation/SimPaths/issues).
58-
59-
60-
### Forking the Repository
61-
62-
1. Click the "Fork" button at the top-right corner of this repository.
63-
2. Untick the `Copy only the main branch` box.
64-
3. This will create a copy of the repository in your own GitHub account.
65-
4. Follow [instructions here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) to periodically synchronize your fork with the most recent version of this ("upstream") repository. This will ensure you use an up-to-date version of the model.
66-
67-
### Setting up your development environment
68-
1. **Java Development Kit (JDK):** Ensure you have a JDK (Java Development Kit) installed on your system. You can download and install the latest version of OpenJDK from [Adoptium](https://adoptium.net/).
69-
2. **Download an IDE** (integrated development environment) of your choice - we recommend [IntelliJ IDEA](https://www.jetbrains.com/idea/download/); download the Community (free) or Ultimate (paid) edition, depending on your needs.
70-
3. Clone your forked repository to your local machine. Import the cloned repository into IntelliJ as a Maven project
71-
72-
### Compiling and running SimPaths with Maven in the CLI
73-
74-
SimPaths can also be compiled by Maven ([installation instructions here](https://maven.apache.org/install.html)) and run from the command line without an IDE. After cloning the repository and setting up the JDK, in the root directory you can run:
75-
```
76-
$ mvn clean package
77-
```
78-
... to create two runnable jars for single- and multi-run SimPaths:
79-
```
80-
.
81-
SimPaths/
82-
...
83-
|-- multirun.jar
84-
|-- singlerun.jar
85-
`-- src
86-
```
87-
88-
To run the SimPathsStart setup phases and set up a population for subsequent multiruns, `singlerun.jar` takes the following options:
89-
90-
- `-c` Country ['UK' or 'IT']
91-
- `-s` Start year
92-
- `-g` [true/false] show/hide gui
93-
- `--rewrite-policy-schedule` Re-write policy schedule from detected policy files
94-
- `-Setup` do setup phases (creating input populations database) only
95-
96-
e.g.
97-
```
98-
$ java -jar singlerun.jar -c UK -s 2017 -g false -Setup
99-
```
100-
For multiple runs, `multirun.jar` takes the following options:
101-
102-
- `-r` random seed for first run (incremented by +1 for subsequent runs)
103-
- `-p` simulated population size
104-
- `-n` number of runs
105-
- `-s` start year of runs
106-
- `-e` end year of runs
107-
- `-g` [true/false] show/hide gui
108-
- `-f` write console output and logs to file (in 'output/logs/run_[seed].txt')
109-
110-
e.g.
111-
```
112-
$ java -jar multirun.jar -r 100 -p 50000 -n 20 -s 2017 -e 2020 -g false -f
113-
```
114-
115-
Run `java -jar singlerun.jar -h` or `java -jar multirun.jar -h` to show these help messages.
116-
117-
### Contributing
118-
119-
1. Create a new branch for your contributions. This will likely be based on either the `main` branch of this repository (if you seek to modify the stable version of the model) or `develop` (if you seek to modify the most recent version of the model). Please see branch naming convention below.
120-
2. Make your changes, add your code, and write tests if applicable.
121-
3. Commit your changes.
122-
4. Push your changes to your fork.
123-
5. Open a Pull Request (PR) on this repository from your fork. Be sure to provide a detailed description of your changes in the PR.
124-
125-
### Branch Naming Conventions
126-
127-
In our open-source project, we follow a clear and consistent branch naming convention to streamline the development process and maintain a structured repository. These conventions help our team of contributors collaborate effectively. Here are the primary branch naming patterns:
128-
129-
1. **Main Branches:**
130-
- `main`: Represents the stable version of our model.
131-
- `develop`: Used for ongoing development and integration of new features.
132-
133-
2. **Feature Branches:**
134-
- `feature/your-feature-name`: Create feature branches for developing new features.
135-
136-
3. **Bug Fix Branches:**
137-
- `bugfix/issue-number-description`: Use bug fix branches for specific issue resolutions. For example, `bugfix/123-fix-health-process-issue`.
138-
139-
6. **Experimental or Miscellaneous Branches:**
140-
- `experimental/your-description`: For experimental or miscellaneous work not tied to specific features or bug fixes. For instance, `experimental/new-architecture`.
141-
142-
7. **Documentation Branches:**
143-
- `docs/documentation-topic`: Prefix documentation branches with `docs` for updating or creating documentation. For example, `docs/update-readme`.
144-
145-
These branch naming conventions are designed to make it easy for our contributors to understand the purpose of each branch and maintain consistency within our repository. Please adhere to these conventions when creating branches for your contributions.
146-
-->
11+
The entire SimPaths documentation is available on its [website](https://centreformicrosimulation.github.io/SimPaths/), which includes: a detailed description of its building blocks; instructions on how to set up and run the model; information about contributing to the model's development.

‎documentation/wiki/developer-guide/internals/multirun-implementation.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,140 @@
33
!!! warning "In progress"
44
This page is under development. Contributions welcome —
55
see the [Developer Guide](../index.md) for how to contribute.
6+
7+
## Running the MultiRun in the command line
8+
9+
### Prerequisites
10+
11+
- Java 19
12+
- Maven 3.8+
13+
- Optional IDE: IntelliJ IDEA (import as a Maven project)
14+
15+
### Build and run
16+
17+
In the command line, navigate to the project directory and run the following commands:
18+
19+
```bash
20+
mvn clean package
21+
java -jar multirun.jar -DBSetup
22+
java -jar multirun.jar
23+
```
24+
25+
The first command builds the JARs. The second creates the H2 donor database from the input data. The third runs the simulation using `default.yml`.
26+
27+
To use a different config file:
28+
29+
```bash
30+
java -jar multirun.jar -config my_run.yml
31+
```
32+
33+
For configuration options, see the annotated `config/default.yml`. For the data pipeline and further reference, see [`documentation/`](documentation/README.md).
34+
35+
<!-- Projections for a workhorse model parameterised to the UK context are reported in [Bronka, P. et al. (2023). *SimPaths: an open-source microsimulation model for life course analysis* (No. CEMPA6/23), Centre for Microsimulation and Policy Analysis at the Institute for Social and Economic Research*](https://www.microsimulation.ac.uk/publications/publication-557738/), which closely reflect observed data throughout a 10-year validation window. -->
36+
37+
38+
<!--
39+
## Getting Started
40+
41+
To contribute to this project, you need to fork the repository and set up your development environment.
42+
43+
### Access to Data
44+
45+
We are committed to maintaining transparency and open-source principles in this project. All the code, documentation, and resources related to our project are available on GitHub for you to explore, use, and contribute to.
46+
47+
The data used by this project is not freely shareable. If you are interested in accessing the data necessary to run the simulation, get in touch with the repository maintainers for further instructions.
48+
49+
However, please note that _training_ data is provided. It allows the simulation to be run and developed, but results obtained on the basis of the training dataset should not be interpreted, except for the purpose of training and development.
50+
51+
**How to Request Access to Data:**
52+
53+
If you have a need for the data, please contact the repository maintainers through the [issue tracker](https://github.com/centreformicrosimulation/SimPaths/issues).
54+
55+
56+
### Forking the Repository
57+
58+
1. Click the "Fork" button at the top-right corner of this repository.
59+
2. Untick the `Copy only the main branch` box.
60+
3. This will create a copy of the repository in your own GitHub account.
61+
4. Follow [instructions here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) to periodically synchronize your fork with the most recent version of this ("upstream") repository. This will ensure you use an up-to-date version of the model.
62+
63+
### Setting up your development environment
64+
1. **Java Development Kit (JDK):** Ensure you have a JDK (Java Development Kit) installed on your system. You can download and install the latest version of OpenJDK from [Adoptium](https://adoptium.net/).
65+
2. **Download an IDE** (integrated development environment) of your choice - we recommend [IntelliJ IDEA](https://www.jetbrains.com/idea/download/); download the Community (free) or Ultimate (paid) edition, depending on your needs.
66+
3. Clone your forked repository to your local machine. Import the cloned repository into IntelliJ as a Maven project
67+
68+
### Compiling and running SimPaths with Maven in the CLI
69+
70+
SimPaths can also be compiled by Maven ([installation instructions here](https://maven.apache.org/install.html)) and run from the command line without an IDE. After cloning the repository and setting up the JDK, in the root directory you can run:
71+
```
72+
$ mvn clean package
73+
```
74+
... to create two runnable jars for single- and multi-run SimPaths:
75+
```
76+
.
77+
SimPaths/
78+
...
79+
|-- multirun.jar
80+
|-- singlerun.jar
81+
`-- src
82+
```
83+
84+
To run the SimPathsStart setup phases and set up a population for subsequent multiruns, `singlerun.jar` takes the following options:
85+
86+
- `-c` Country ['UK' or 'IT']
87+
- `-s` Start year
88+
- `-g` [true/false] show/hide gui
89+
- `--rewrite-policy-schedule` Re-write policy schedule from detected policy files
90+
- `-Setup` do setup phases (creating input populations database) only
91+
92+
e.g.
93+
```
94+
$ java -jar singlerun.jar -c UK -s 2017 -g false -Setup
95+
```
96+
For multiple runs, `multirun.jar` takes the following options:
97+
98+
- `-r` random seed for first run (incremented by +1 for subsequent runs)
99+
- `-p` simulated population size
100+
- `-n` number of runs
101+
- `-s` start year of runs
102+
- `-e` end year of runs
103+
- `-g` [true/false] show/hide gui
104+
- `-f` write console output and logs to file (in 'output/logs/run_[seed].txt')
105+
106+
e.g.
107+
```
108+
$ java -jar multirun.jar -r 100 -p 50000 -n 20 -s 2017 -e 2020 -g false -f
109+
```
110+
111+
Run `java -jar singlerun.jar -h` or `java -jar multirun.jar -h` to show these help messages.
112+
113+
### Contributing
114+
115+
1. Create a new branch for your contributions. This will likely be based on either the `main` branch of this repository (if you seek to modify the stable version of the model) or `develop` (if you seek to modify the most recent version of the model). Please see branch naming convention below.
116+
2. Make your changes, add your code, and write tests if applicable.
117+
3. Commit your changes.
118+
4. Push your changes to your fork.
119+
5. Open a Pull Request (PR) on this repository from your fork. Be sure to provide a detailed description of your changes in the PR.
120+
121+
### Branch Naming Conventions
122+
123+
In our open-source project, we follow a clear and consistent branch naming convention to streamline the development process and maintain a structured repository. These conventions help our team of contributors collaborate effectively. Here are the primary branch naming patterns:
124+
125+
1. **Main Branches:**
126+
- `main`: Represents the stable version of our model.
127+
- `develop`: Used for ongoing development and integration of new features.
128+
129+
2. **Feature Branches:**
130+
- `feature/your-feature-name`: Create feature branches for developing new features.
131+
132+
3. **Bug Fix Branches:**
133+
- `bugfix/issue-number-description`: Use bug fix branches for specific issue resolutions. For example, `bugfix/123-fix-health-process-issue`.
134+
135+
6. **Experimental or Miscellaneous Branches:**
136+
- `experimental/your-description`: For experimental or miscellaneous work not tied to specific features or bug fixes. For instance, `experimental/new-architecture`.
137+
138+
7. **Documentation Branches:**
139+
- `docs/documentation-topic`: Prefix documentation branches with `docs` for updating or creating documentation. For example, `docs/update-readme`.
140+
141+
These branch naming conventions are designed to make it easy for our contributors to understand the purpose of each branch and maintain consistency within our repository. Please adhere to these conventions when creating branches for your contributions.
142+
-->

0 commit comments

Comments
 (0)