Package: fargopy
FARGOpyWrapping FRAGO3DFARGOpyis a python wrapping forFARGO3D, the well-knwon hydrodynamics and magnetohydrodynamics parallel code. This wrapping is intended to facillitate the interaction with FARGO3D, especially for those starting using the code.FARGOpymay be also useful for teaching and training purposes. For advanced users,FARGOpyprovides useful functionalities in the postprocessing of simulation results, derivative calculations and plots.This is an animation created with a few lines of code usingFARGOpy.For the code used to generate this animation see the tutorial notebookanimations withFARGOpy. For other examples and a full tutorial see theexamples repository.InstallingFARGOpyFARGOpyis available at thePythonpackage index and can be installed using:$sudopipinstallfargopyas usual this command will install all dependencies (excludingFARGO3Dwhich must be installed indepently as explained before) and download some useful data, scripts and constants.NOTE: If you don't have access tosudo, you can installFARGOpyin your local environmen (usually at~/.local/). In that case you need to add to yourPATHenvironmental variable the location of the local python installation. Add to~/.bashrcthe lineexport PATH=$HOME/.local/bin:$PATHSinceFARGOpyis a python wrap forFARGO3Dthe ideal environment to work with the package isIPython/Jupyter. It works really fine inGoogle Colabensuing training and demonstration purposes. This README, for instance, can be ran inGoogle Colab:This code only works in Colab and it is intended to install the latest version ofFARGOpyimportsysif'google.colab'insys.modules:!sudopipinstall-UqfargopyIf you are working inJupyteror inGoogle Colab, the configuration directory and its content will be crated the first time you import the package:importfargopyasfp# These lines are intented for developing purposes; drop them in your code%load_extautoreload%autoreload2Running FARGOpy version 0.3.6If you are working on a remote Linux server, it is better to run the package usingIPython. For this purpose, after installation,FARGOpyprovides a special initialization command:$ifargopyThe first time you run this script, it will create a configuration directory~/.fargopy(with~the abbreviation for the home directory). This directory contains a set of basic configuration variables which are stored in the file~/.fargopy/fargopyrc. You may change this file if you want to customize the installation. The configuration directory also contains theIPythoninitialization script~/.fargopy/ifargopy.py.Downloading and installing FARGO3DIt is important to understand thatFARGO3Dworks especially well on Linux plaforms (includingMacOS). The same condition applies forFARGOpy. Because of that, most of the internal as well as the public features of the packages are designed to work in aLinuxenvironment. For working in other operating systems, especially on MS Windows, please consider using virtual machines ow WSL.Being an independent project,FARGOpyis not provided with a working version ofFARGO3D. You need to download the C package and their prerequisites (compilers, third-party libraries, etc.) and configure them, by yourself. For a detailed guide please see theFARGO3D documentationor theproject repo at bitbucket.StillFARGOpyprovides a simple way to get the latest version of the source code ofFARGO3Dfrom its public GitHub repository. The source code will be downloaded into the home directory and stored as~/fargo3d/.WARNING: If you want to change the final location of the source code or the name of theFARGO3Ddirectory,  before executing the following command, please change the corresponding configuration variables in~/.fargopy/fargopyrcTo download theFARGO3Dsource code execute:fp.initialize('download',force=True)Downloading FARGOpy...
Directory '/home/jzuluaga/fargo3d/' already exists. Removing it...


Cloning into 'fargo3d'...


	FARGO3D downloaded to /home/jzuluaga/fargo3d/
Header file for FARGO3D found in the fargo directory /home/jzuluaga/fargo3d/Once download it you may check if the source code is compiling in your machine. For that purpose run:fp.initialize('check',regular=1,gpu=0,parallel=0)Test compilation of FARGO3D
	Checking normal compilation.
	Running 'make -C /home/jzuluaga/fargo3d/ clean mrproper all PARALLEL=0 GPU=0 2>&1 |tee /tmp/fargo_regular.log':
		Compilation in mode regular successful.
	Skipping gpu compilation
	Skipping parallel compilation
Summary of compilation modes:
	Regular: 1
	GPU: 0
	Parallel: 0If you have some error at compilingFARGO3Din some of the possible modes (regular, gpu and/or parallel) please check the corresponding logfile and correct the problems. Compiling problems will normally arise because of a lacking of an important dependency, for instance a compiler, a driver (in the case of GPU) or a third-party library or tool (eg. openmpi).QuickstartHere we will illustrate the minimal commands you may run to test the package. A more detailed set of examples can be found exploringthe tutorial notebooks. Other in depth examples are also available in theexamples repositoryof theGitHubrepository.There are two complimentary modes when usingFARGOpy:Control mode: Using this mode you can run and controlFARGO3Dfrom your notebook.  This mode requires a working copy ofFARGO3Dready to be compiled and run. This mode is ideal for training or testing purposes.Postprocessing mode: UsingFARGOpyin this mode allows you to process some of the output files produced by aFARGO3Dsimulation. This mode does not necesarily requires that a working copy ofFARGO3Dbe installed in the machine where you are performing the postprocessing analysis. This mode is ideal for advanced users.Control modeCreate a simulation:sim=fp.Simulation(setup='fargo')Your simulation is now connected with '/home/jzuluaga/fargo3d/'
Now your simulation setup is at '/home/jzuluaga/fargo3d/setups/fargo'Compile theFARGO3Dbinary to run the simulation:sim.compile(parallel=0,gpu=0)Compiling fargo3d_SETUP-fargo_PARALLEL-0_GPU-0...
Succesful compilation of FARGO3D binary fargo3d_SETUP-fargo_PARALLEL-0_GPU-0Run the simulation:sim.run(cleanrun=True)Cleaning output directory /home/jzuluaga/fargo3d/outputs/fargo
Running asynchronously (test = False):  ./fargo3d_SETUP-fargo_PARALLEL-0_GPU-0 -m -t setups/fargo/fargo.par
Now you are connected with output directory '/home/jzuluaga/fargo3d/outputs/fargo'
Found a variables.par file in '/home/jzuluaga/fargo3d/outputs/fargo', loading properties
Loading variables
84 variables loaded
Simulation in 2 dimensions
Loading domain in cylindrical coordinates:
	Variable phi: 384 [[0, -3.1334114227210694], [-1, 3.1334114227210694]]
	Variable r: 128 [[0, 0.408203125], [-1, 2.491796875]]
	Variable z: 1 [[0, 0.0], [-1, 0.0]]
Number of snapshots in output directory: 1
Configuration variables and domains load into the object. See e.g. <sim>.varsYou may check the status:sim.status()################################################################################
Running status of the process:
	The process is running.Or check the progress of the simulation:sim.status('progress')Progress of the simulation (numstatus = 5, interrupting may stop the process):
1:OUTPUTS 3 at date t = 18.849556 OK [output pace = 0.1 secs]
2:OUTPUTS 4 at date t = 25.132741 OK [output pace = 0.1 secs]
3:OUTPUTS 5 at date t = 31.415927 OK [output pace = 0.9 secs]
4:OUTPUTS 6 at date t = 37.699112 OK [output pace = 1.8 secs]
5:OUTPUTS 7 at date t = 43.982297 OK [output pace = 1.9 secs]You may stop the simulation at any time using:sim.stop()Stopping FARGO3D process (pid = 26257)Check the status of the simulation using:sim.status('summary')The simulation has been ran for 9 time-steps (including the initial one).Once stopped you may resume the simulation at any snapshot or at the latest resumable snapshot:sim.resume()Resuming from snapshot 7...
Running asynchronously (test = False):  ./fargo3d_SETUP-fargo_PARALLEL-0_GPU-0 -m -t -S 7 -t setups/fargo/fargo.par
Now you are connected with output directory '/home/jzuluaga/fargo3d/outputs/fargo'
Found a variables.par file in '/home/jzuluaga/fargo3d/outputs/fargo', loading properties
Loading variables
84 variables loaded
Simulation in 2 dimensions
Loading domain in cylindrical coordinates:
	Variable phi: 384 [[0, -3.1334114227210694], [-1, 3.1334114227210694]]
	Variable r: 128 [[0, 0.408203125], [-1, 2.491796875]]
	Variable z: 1 [[0, 0.0], [-1, 0.0]]
Number of snapshots in output directory: 9
Configuration variables and domains load into the object. See e.g. <sim>.varsOnce the simulation has been completed you will notice by ran:sim.stop()The process has finished. Check logfile /home/jzuluaga/fargo3d/setups/fargo/fargo.log.Postprocessing modeNow that you have some results to process, it is time to use the functionalities thatFARGOpyprovides for this purpose.Create the simulation and connect it to the output directory:sim=fp.Simulation(output_dir=fp.Conf.FP_FARGO3D_DIR+'/outputs/fargo')Your simulation is now connected with '/home/jzuluaga/fargo3d/'
Now you are connected with output directory '/home/jzuluaga/fargo3d//outputs/fargo'
Found a variables.par file in '/home/jzuluaga/fargo3d//outputs/fargo', loading properties
Loading variables
84 variables loaded
Simulation in 2 dimensions
Loading domain in cylindrical coordinates:
	Variable phi: 384 [[0, -3.1334114227210694], [-1, 3.1334114227210694]]
	Variable r: 128 [[0, 0.408203125], [-1, 2.491796875]]
	Variable z: 1 [[0, 0.0], [-1, 0.0]]
Number of snapshots in output directory: 21
Configuration variables and domains load into the object. See e.g. <sim>.varssim.load_properties()Loading variables
84 variables loaded
Simulation in 2 dimensions
Loading domain in cylindrical coordinates:
	Variable phi: 384 [[0, -3.1334114227210694], [-1, 3.1334114227210694]]
	Variable r: 128 [[0, 0.408203125], [-1, 2.491796875]]
	Variable z: 1 [[0, 0.0], [-1, 0.0]]
Number of snapshots in output directory: 22
Configuration variables and domains load into the object. See e.g. <sim>.varsLoad gas density field from a given snapshot:gasdens=sim.load_field('gasdens',snapshot=20)Create ameshsliceof the field:gasdens_r,mesh=gasdens.meshslice(slice='z=0,phi=0')Plot the slice:importmatplotlib.pyplotaspltifnotfp.IN_COLAB:plt.ioff()# Drop this out of this tutorialfig,ax=plt.subplots()ax.semilogy(mesh.r,gasdens_r)ax.set_xlabel(r"$r$ [cu]")ax.set_ylabel(r"$\rho$ [cu]")fp.Plot.fargopy_mark(ax)ifnotfp.IN_COLAB:fig.savefig('gallery/example-dens_r.png')# Drop this out of this tutorialYou may also create a 2-dimensionalmeshslice:gasdens_plane,mesh=gasdens.meshslice(slice='z=0')And plot it:ifnotfp.IN_COLAB:plt.ioff()# Drop this out of this tutorialfig,axs=plt.subplots(1,2,figsize=(12,6))ax=axs[0]ax.pcolormesh(mesh.phi,mesh.r,gasdens_plane,cmap='prism')ax.set_xlabel('$\phi$ [rad]')ax.set_ylabel('$r$ [UL]')fp.Plot.fargopy_mark(ax)ax=axs[1]ax.pcolormesh(mesh.x,mesh.y,gasdens_plane,cmap='prism')ax.set_xlabel('$x$ [UL]')ax.set_ylabel('$y$ [UL]')fp.Plot.fargopy_mark(ax)ax.axis('equal')ifnotfp.IN_COLAB:fig.savefig('gallery/example-dens_disk.png')# Drop this out of this tutorialWorking with precomputed simulationsIf you don't have the resources to compile or runFARGO3Dand still you want to test the postprocessing functionalities of the package you may download a precomputed simulation:fp.Simulation.download_precomputed(setup='fargo')Downloading fargo.tgz from cloud (compressed size around 55 MB) into /tmp


Downloading...
From: https://docs.google.com/uc?export=download&id=1YXLKlf9fCGHgLej2fSOHgStD05uFB2C3
To: /tmp/fargo.tgz
100%|██████████| 54.7M/54.7M [00:02<00:00, 19.1MB/s]


Uncompressing fargo.tgz into /tmp/fargo
Done.Once downloaded you may connect with simulation using:sim=fp.Simulation(output_dir='/tmp/fargo')Your simulation is now connected with '/home/jzuluaga/fargo3d/'
Now you are connected with output directory '/tmp/fargo'and perform the postprocessing as explained before.We have prepared a set of precomputed simulations covering some interesting scientific cases. You may see the list of precomputed simulations available in theFARGOpycloud repository:fp.Simulation.list_precomputed()fargo:
	Description: Protoplanetary disk with a Jovian planet [2D]
	Size: 55 MB
p3diso:
	Description: Protoplanetary disk with a Super earth planet [3D]
	Size: 220 MB
p3disoj:
	Description: Protoplanetary disk with a Jovian planet [3D]
	Size: 84 MB
fargo_multifluid:
	Description: Protoplanetary disk with several fluids (dust) and a Jovian planet in 2D
	Size: 100 MB
binary:
	Description: Disk around a binary with the properties of Kepler-38 in 2D
	Size: 140 MBYou may find in theexamples directoryof theGitHubrepository, example notebooks illustrating how to useFARGOpyfor processing the output of this precomputed simulations.What's newVersion 0.3.*:Refactoring of initializing routines.Improvements in documentation of basic classes in__init__.py.Precomputed simulations uploaded to FARGOpy Cloud Repository and available usnigdownload_precomputedstatic method.Version 0.2.*:First real applications tested with FARGOpy.All basic routines for reading output created.Major refactoring.Version 0.1.*:Package is now provided with a script 'ifargopy' to run 'ipython' with fargopy initialized.A new 'progress' mode has been added to status method.All the dynamics of loading/compiling/running/stoppìng/resuming FARGO3D has been developed.Version 0.0.*:First classes created.The project is started!This package has been designed and written mostly by Jorge I. Zuluaga with advising and contributions by Matías Montesinos (C) 2023