diff --git a/source/installation/howto-web-no-local-install.md b/source/installation/howto-web-no-local-install.md deleted file mode 100644 index fa3166ad..00000000 --- a/source/installation/howto-web-no-local-install.md +++ /dev/null @@ -1,24 +0,0 @@ -# On the web - -Some online services offer the opportunity to run Python code without having to install anything on your machine. - -If you wish to run OpenFisca directly on your browser for a simulation or to evaluate the impact of a reform, you might find one of the following services useful: [Gitpod](https://www.gitpod.io/), [repl.it](https://repl.it), [python anywhere](https://www.pythonanywhere.com) and [Jupyterlab](https://jupyterlab.readthedocs.io/en/stable/). - -Please be aware that you might need to install the OpenFisca package you need on your online service before using it. You will find a quick generic usage example to test your setup below. - -## Instructions - -1. Start by installing the package you need on your online service e.g. `OpenFisca-Country-Template`. - -2. Write the code you wish to run. Example of a code snippet to run: - - ```py - from openfisca_country_template import CountryTaxBenefitSystem - - tax_benefit_system = CountryTaxBenefitSystem() - parameters = tax_benefit_system.parameters - - print(parameters) - ``` - -3. Run your code and check the results. diff --git a/source/installation/index.md b/source/installation/index.md index 2b6919a8..c30c07d7 100644 --- a/source/installation/index.md +++ b/source/installation/index.md @@ -3,7 +3,7 @@ ```{toctree} :hidden: -howto-web-no-local-install +on-the-web howto_docker offline-environment windows-no-admin @@ -12,12 +12,12 @@ test_situations As the OpenFisca community becomes larger, issues that only affect a small percentage of users arise. -The purpose of this section is to bring together the clever solutions the community came up with and share them with all OpenFisca users. +The purpose of this section is to bring together clever solutions the community comes up with and share them with all OpenFisca users. -- [How to use OpenFisca on the web (no installation required on your computer)](./howto-web-no-local-install.md) +- [How to use OpenFisca on the web (no installation required on your computer)](./on-the-web.md) - [How to use OpenFisca with Docker](./howto_docker.md) - [How to install OpenFisca in an offline environment](./offline-environment.md) - [How to work on OpenFisca on a Windows without being administrator](./windows-no-admin.md) - [How to test your changes on "ready to use" situations](./test_situations.md) -> You're welcome to share your tips on how to solve technical issues! Please update [this section](https://github.com/openfisca/openfisca-doc/edit/master/recipes.md) (in English) or this [wiki FAQ](https://github.com/openfisca/tutorial/wiki) in your preferred language. +> You're welcome to share your tips on how to solve technical issues! Please suggest updates, create pull requests in this [section](https://github.com/openfisca/openfisca-doc/edit/master/recipes.md). Note: it is intended this documentation is in English. diff --git a/source/installation/offline-environment.md b/source/installation/offline-environment.md index 863ec523..b4d82fc3 100644 --- a/source/installation/offline-environment.md +++ b/source/installation/offline-environment.md @@ -1,61 +1,68 @@ # In an offline environment -If you need to install OpenFisca on a server with no Internet access, here is how to do it. +If you need to install OpenFisca on a server with no internet access, here is how you might do it. -The big picture: download Python packages on a machine with Internet access, copy them to the server and install them in a [virtualenv](https://virtualenv.pypa.io/en/stable/). +The big picture: download Python packages on a machine with internet access, copy them to the server and install them in a [virtualenv](https://virtualenv.pypa.io/en/stable/). -We assume that it is possible to copy files to the server, for example via a USB stick. Or perhaps the server filters only outgoing connections, but accepts incoming connections allowing to copy the files. +It's assumed that it is possible to copy files to the server, i.e. via a USB stick. ## On the machine with Internet access -We are going to create a first virtualenv in which we'll use `pip` to download the `.whl` files in a specific directory. - -Here we use [pew](https://github.com/berdario/pew) to simplify virtualenv management. +First create a virtual environment and use `pip` to download the `.whl` files to a specific directory. ```sh -pip install pew -pew new openfisca-packages --python=python3.7 +mkdir ~/openfisca-packages +cd ~/openfisca-packages + +# Create and instigate a virtual environment +python3.11 -m venv .venv +source .venv/bin/activate # Upgrade pip itself pip install --upgrade pip pip --version -# Should print at least 9.0 at the time we write this doc. +# Prints 24.0 at the time this doc was written. -mkdir ~/openfisca-packages -cd ~/openfisca-packages -pip download OpenFisca-France +mkdir country-template +cd country-template +pip download OpenFisca-Country-Template # You should see the downloaded files in the current directory. ``` -Now copy these files on the server (say in the `~/openfisca-packages` directory), either via a USB stick, or with `scp`, or any other way. +Copy the files in the `~/openfisca-packages/country-template` directory to the server via a USB stick, or for example with `scp`. Example with `scp`: ```sh -scp -r ~/openfisca-packages user@server: +scp -r ~/openfisca-packages/country-template user@server: ``` ## On the server -Starting from here we assume you copied the packages on the server, say in `~/openfisca-packages`. +The following assumes the files are now stored in `~/openfisca-packages/country-template` on the server. The following commands show how to install Python packages without any Internet access. -If you already have a virtualenv, activate it. Otherwise create a new one following the same instructions as above (for example with `pew new`). +If you already have a virtual environment, activate it. Otherwise create a new one following the same instructions as above. ```sh -pip install ~/openfisca-packages/* + pip install ~/openfisca-packages/country-template/* Processing ./isodate-0.5.4.tar.gz [...] - Installing collected packages: pytz, Babel, Biryani, numpy, PyYAML, OpenFisca-Core, requests, OpenFisca-France, isodate - Successfully installed Babel-2.3.4 Biryani-0.10.4 OpenFisca-Core-7.0.0 OpenFisca-France-15.1.0 PyYAML-3.12 isodate-0.5.4 numpy-1.12.0 pytz-2016.10 requests-2.13.0 + Installing collected packages: StrEnum, sortedcontainers, typing-extensions... openfisca-country-template + Successfully installed StrEnum, sortedcontainers, typing-extensions... openfisca-country-template -pip list | grep OpenFisca-France - OpenFisca-France 15.1.0 + # Step completed, the following can be utilised to confirm success and versions of the packages installed. + pip list | grep openfisca-country_template + openfisca-country_template 7.1.1 + + pip list | grep OpenFisca-Core + OpenFisca-Core 41.4.5 ``` -Run the basic tests which confirm that OpenFisca-France is correctly installed: +To check that everything works correctly, run the following command: ```sh -python -m openfisca_france.tests.test_basics -OpenFisca-France basic test was executed successfully. +python -c "from openfisca_country_template import CountryTaxBenefitSystem; CountryTaxBenefitSystem()" ``` + +No error message should appear. You can now utilise this environment to [run simulations](../simulate/run-simulation.md). \ No newline at end of file diff --git a/source/installation/on-the-web.md b/source/installation/on-the-web.md new file mode 100644 index 00000000..162f7a99 --- /dev/null +++ b/source/installation/on-the-web.md @@ -0,0 +1,24 @@ +# On the web + +Some online services offer the opportunity to run Python code without having to install anything on your machine. + +For example, if you wish to evaluate the impact of a reform you could decide to run an OpenFisca simulation directly in your browser. To achieve this you might find one of the following services useful: [Gitpod](https://www.gitpod.io/), [repl.it](https://repl.it), [python anywhere](https://www.pythonanywhere.com) and [Jupyterlab](https://jupyterlab.readthedocs.io/en/stable/). + +Please be aware that you will need to install the OpenFisca package you need on your online service before using it. You will find a quick generic usage example to test your setup below. + +## Instructions + +1. Start by installing the package you need on your online service e.g. `pip install openfisca-country-template`. + +2. Write the code you wish to run. The following code snippet works with the above package: + + ```py + from openfisca_country_template import CountryTaxBenefitSystem + + tax_benefit_system = CountryTaxBenefitSystem() + parameters = tax_benefit_system.parameters + + print(parameters) + ``` + +3. Run your code and check the results. diff --git a/source/installation/test_situations.md b/source/installation/test_situations.md index a4cd69df..dc0644e6 100644 --- a/source/installation/test_situations.md +++ b/source/installation/test_situations.md @@ -1,7 +1,6 @@ -# How to test your changes on "ready to use" situations (for OpenFisca-France) +# How to test your changes on "ready to use" situations -Often, when making changes to legislation, you need to test it on a situation that works with your country's tax and benefit system. -Sometimes, these situations can be quite complicated to model (such as roomates). -Instead of re-writing them everytime, we have pre-packaged a few in a Python Package. - -You can find the package along with a usage example in the [Tutorial repository](https://github.com/openfisca/tutorial/tree/master/python/scripts/generate_situation_examples) +Often, when making changes to legislation it needs testing on a simulation that works with your country's tax and benefit system. +Sometimes, these simulations can be quite complicated to model. +Instead of rewriting them every time, first check your country's repository for `situation_examples` that have already been created. +If what you need does not exist, you could create your own examples and contribute them to the repository. diff --git a/source/installation/windows-no-admin.md b/source/installation/windows-no-admin.md index 482ddcc4..e193b67b 100644 --- a/source/installation/windows-no-admin.md +++ b/source/installation/windows-no-admin.md @@ -13,20 +13,20 @@ Git is a tool that will help you version your work. It also comes with a shell * ## 2. Install Python -Python is the programing language used in OpenFisca. It can be installed without administrators rights through a software named Miniconda. +Python is the programming language used in OpenFisca. It can be installed without administrator rights through a software named Miniconda. -- Download miniconda from [https://conda.io/miniconda](https://conda.io/miniconda). Make sure to choose the **Python 3.7** version for Windows. If you don't know if your system is 32-bit or 64-bit, pick 32-bit. -- Install it. At some point, the installer will ask you for a "Destination Folder". You can keep the default or choose another one, but in all case **copy paste the path to this folder somewhere**. It will be useful later. For instance, this path may look like `C:\Users\my-name\AppData\Local\Miniconda2`. +- Download miniconda from [https://conda.io/miniconda](https://conda.io/miniconda). Make sure to choose the **Python 3.11** version for Windows. If you don't know if your system is 32-bit or 64-bit, pick 32-bit. +- Install it. At some point, the installer will ask you for a "Destination Folder". You can keep the default or choose another one, in any case **copy-paste the path to this folder somewhere** as it will be useful later. For instance, this path may look like `C:\Users\my-name\AppData\Local\Miniconda2`. - Run the program "Git Bash" from the "Start" menu. This should open a command line. Copy and paste the following lines in the console, after **adapting the first line using the path you noted in the last step**: ```sh -echo 'MINICONDA_PATH="C:\Users\form\AppData\Local\Miniconda2"' >> .bashrc +echo 'MINICONDA_PATH="C:\Users\my-name\AppData\Local\Miniconda2"' >> .bashrc echo 'function convert { echo /$1 | sed '\''s/\\/\//g'\'' | sed '\''s/://'\'' ; }' >> .bashrc echo 'function add { export PATH=$(convert $1):$PATH ;}' >> .bashrc echo 'add $MINICONDA_PATH' >> .bashrc echo 'add "$MINICONDA_PATH/Scripts"' >> .bashrc source .bashrc -conda create -n openfisca python=3.7 --offline --yes +conda create -n openfisca python=3.11 --offline --yes echo 'source activate openfisca' >> .bashrc source activate openfisca ``` @@ -41,12 +41,14 @@ A version number should be printed, and no error message should appear. Congrats ## 3. Install OpenFisca +For this example, we will utilise the `OpenFisca-France` package. For a different model you could achieve the same result by following the [offline environment](offline-environment) example to get local copies of the required packages. + - Download the OpenFisca-France [installation files](https://github.com/openfisca/openfisca-france-offline/archive/master.zip) -- Extract the content of this archive in a directory. -- Go to that directory, then to the `windows` subdirectory. If you installed Python in 32 bits, **right-click** on `32-bits`. If you installed Python in 64 bits, **right-click** on the `64-bits` subdirectory. Choose "Git Bash Here" +- Extract the content of this archive into a directory. +- Go to that directory and then to the `windows` subdirectory. If you installed Python in 32 bits, **right-click** on `32-bits`. If you installed Python in 64 bits, **right-click** on the `64-bits` subdirectory. Choose "Git Bash Here" - Run the command `pip install *` -To check that everything worked correctly, type in Git Bash: +To check that everything works correctly, run the following command in Git Bash: ```sh python -c "from openfisca_france import CountryTaxBenefitSystem; CountryTaxBenefitSystem()" @@ -56,7 +58,7 @@ No error message should appear. Congrats, you just installed OpenFisca-France! ## 4. Install atom -Atom is a modern text editor that doesn't require administrator priviledges to be installed. It will allow you to edit Python files with syntaxing coloring. +Atom is a modern text editor that doesn't require administrator privileges to be installed. It will allow you to edit Python files with syntaxing colouring. - Download atom from [https://atom.io/](https://atom.io/)